@dailephd/my-dev-kit-lab 0.2.2 → 0.3.1

package/dist/src/audits/core/languageAnalyzerRegistry.js

@@ -0,0 +1,33 @@
+import { TYPESCRIPT_JAVASCRIPT_ANALYZER } from "./typescriptJavaScriptAnalyzer.js";
+// Validates a list has no duplicate analyzer ids. Later batches call this
+// when assembling their own registries; Batch 2's empty default trivially
+// passes.
+export function createLanguageAnalyzerRegistry(analyzers) {
+    const seen = new Set();
+    for (const analyzer of analyzers) {
+        if (seen.has(analyzer.id)) {
+            throw new Error(`Duplicate language analyzer id: "${analyzer.id}".`);
+        }
+        seen.add(analyzer.id);
+    }
+    return analyzers;
+}
+// First matching analyzer in registry order (deterministic), or null when
+// none supports the given language/extension. Order is preserved from the
+// input registry -- not re-sorted.
+export function selectLanguageAnalyzer(registry, language, extension) {
+    for (const analyzer of registry) {
+        if (!analyzer.supportedLanguages.includes(language))
+            continue;
+        if (analyzer.supportedExtensions && !analyzer.supportedExtensions.includes(extension))
+            continue;
+        return analyzer;
+    }
+    return null;
+}
+// v0.3.1 Batch 3 -- registers the TypeScript/JavaScript analyzer. Python,
+// Java, and Kotlin remain fallback-only (no analyzer registered for them) --
+// see collectSourceFacts.ts's fallback policy.
+export const DEFAULT_LANGUAGE_ANALYZER_REGISTRY = createLanguageAnalyzerRegistry([
+    TYPESCRIPT_JAVASCRIPT_ANALYZER,
+]);

package/dist/src/audits/core/projectInventory.js

@@ -0,0 +1,458 @@
+import fs from "node:fs";
+import path from "node:path";
+import { relativeWithinRoot } from "../../core/pathSafety.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 2 — deterministic project inventory scanner.
+//
+// Pure data collection: this module classifies files and produces counts. It
+// deliberately never returns an AuditIssue -- that begins in a later
+// detector batch. Reused pattern from src/core/pathSafety.ts for path
+// normalization/containment (relativeWithinRoot already forward-slash
+// normalizes, matching the "path separators normalize consistently"
+// requirement), but this scanner is its own walker rather than reusing
+// src/core/fileGlobs.ts's private walkFiles(), because inventory needs a
+// different, broader exclusion set (notably "reports", which fileGlobs.ts's
+// scanner does not exclude) and a wider default surface (docs, tests, CI,
+// package, config -- not just src/scripts).
+// ---------------------------------------------------------------------------
+export const INVENTORY_FILE_CATEGORIES = [
+    "source",
+    "tests",
+    "docs",
+    "package",
+    "config",
+    "scripts",
+    "ci",
+    "generated",
+    "report",
+    "unknown",
+];
+// ---------------------------------------------------------------------------
+// v0.3.1 Batch 1 — normalized language and file-role metadata.
+//
+// Purely additive to the v0.3.0 category model above: `category` keeps its
+// existing meaning and existing consumers (detectors, report model) are
+// untouched. `language` and `role` are deterministic, extension/path-based
+// classifications layered on top so later v0.3.1 batches (language analyzer
+// registry, per-language code-rot detectors) can select files by language
+// without re-deriving it from extensions themselves. Language detection is
+// classification-only here -- it does not imply parsing/analysis support for
+// python/java/kotlin exists yet.
+// ---------------------------------------------------------------------------
+export const NORMALIZED_LANGUAGES = [
+    "typescript",
+    "javascript",
+    "python",
+    "java",
+    "kotlin",
+    "json",
+    "markdown",
+    "yaml",
+    "xml",
+    "toml",
+    "unknown",
+];
+const EXTENSION_TO_LANGUAGE = {
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".py": "python",
+    ".java": "java",
+    ".kt": "kotlin",
+    ".kts": "kotlin",
+    ".json": "json",
+    ".md": "markdown",
+    ".markdown": "markdown",
+    ".yml": "yaml",
+    ".yaml": "yaml",
+    ".xml": "xml",
+    ".toml": "toml",
+};
+function classifyLanguage(extension) {
+    return EXTENSION_TO_LANGUAGE[extension] ?? "unknown";
+}
+export const FILE_ROLES = [
+    "source",
+    "test",
+    "docs",
+    "config",
+    "package",
+    "generated",
+    "build-output",
+    "vendor",
+    "report-output",
+    "unknown",
+];
+// Path-segment markers used only when a file wasn't already excluded from
+// traversal entirely (EXCLUDED_DIR_NAMES below) -- e.g. paths reachable from
+// nested benchmark/fixture projects, or directories not yet in the hard
+// exclusion set. Deliberately conservative: matched as whole path segments,
+// not substrings.
+const VENDOR_PATH_SEGMENTS = new Set(["node_modules", "vendor"]);
+const BUILD_OUTPUT_PATH_SEGMENTS = new Set(["dist", "build", "out", ".next", ".turbo", "target", ".gradle"]);
+const GENERATED_PATH_SEGMENTS = new Set([
+    "generated",
+    ".cache",
+    ".my-dev-kit",
+    ".my-dev-kit-v1",
+    ".my-dev-kit-lab",
+]);
+const REPORT_OUTPUT_PATH_SEGMENTS = new Set(["reports", "lab-output"]);
+function classifyFileRole(relativePath, basename, extension, category) {
+    const segments = relativePath.split("/");
+    if (category === "report" ||
+        isStrayReportFile(basename) ||
+        segments.some((s) => REPORT_OUTPUT_PATH_SEGMENTS.has(s))) {
+        return "report-output";
+    }
+    if (segments.some((s) => VENDOR_PATH_SEGMENTS.has(s)))
+        return "vendor";
+    if (extension === ".tsbuildinfo" || segments.some((s) => BUILD_OUTPUT_PATH_SEGMENTS.has(s)))
+        return "build-output";
+    if (extension === ".map" || segments.some((s) => GENERATED_PATH_SEGMENTS.has(s)))
+        return "generated";
+    switch (category) {
+        case "tests":
+            return "test";
+        case "docs":
+            return "docs";
+        case "package":
+            return "package";
+        case "config":
+        case "ci":
+            return "config";
+        case "source":
+        case "scripts":
+            return "source";
+        default:
+            return "unknown";
+    }
+}
+// Directory names excluded from traversal entirely -- never descended into.
+const EXCLUDED_DIR_NAMES = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "coverage",
+    "reports",
+    "lab-output",
+    ".my-dev-kit",
+    ".my-dev-kit-v1",
+    ".my-dev-kit-lab",
+    "__pycache__",
+    ".idea",
+    ".vscode",
+    // Vitest's own local cache directory (gitignored) -- generated tool
+    // output, same category as coverage/.
+    ".vitest",
+]);
+// OS/editor noise filenames, mirroring .gitignore's own conventions.
+const EXCLUDED_FILE_NAMES = new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
+function isNoiseFile(basename) {
+    return EXCLUDED_FILE_NAMES.has(basename) || basename.endsWith(".swp") || basename.endsWith("~");
+}
+// Known package/manifest filenames -> "package" category.
+const PACKAGE_FILE_NAMES = new Set([
+    "package.json",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "npm-shrinkwrap.json",
+    "LICENSE",
+    ".npmrc",
+]);
+// Known binary/media extensions -- never read for content (line count, etc).
+const BINARY_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".ico",
+    ".pdf",
+    ".zip",
+    ".tgz",
+    ".tar",
+    ".gz",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".eot",
+    ".exe",
+    ".dll",
+    ".so",
+    ".dylib",
+    ".wasm",
+    ".db",
+    ".sqlite",
+]);
+const KNOWN_SOURCE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    // v0.3.1 Batch 2 fix: .kt/.kts were classified as a NormalizedLanguage
+    // ("kotlin") since Batch 1 but were missing here, so a Kotlin file under
+    // src/ got category "unknown" (role "unknown") instead of "source" --
+    // silently excluding it from source-facts collection. .go/.rs above are
+    // intentionally left as "source" despite having no NormalizedLanguage
+    // mapping yet (they normalize to language "unknown"), which is the
+    // legitimate "known role, unknown language" case collectSourceFacts.ts's
+    // fallback policy handles.
+    ".kt",
+    ".kts",
+    // v0.3.1 Batch 3 fix: same class of gap as the .kt/.kts fix above -- .mts
+    // and .cts were mapped to NormalizedLanguage "typescript" since Batch 1
+    // but were missing here, so a .mts/.cts file under src/ got category
+    // "unknown" (role "unknown") and would never reach the Batch 3
+    // TypeScript/JavaScript analyzer's eligibility filter (role source/test
+    // only, see collectSourceFacts.ts).
+    ".mts",
+    ".cts",
+]);
+// A file this large or larger is skipped entirely (not even stat'd into the
+// inventory) -- protects against pathological huge-file scan cost.
+const DEFAULT_HARD_SKIP_FILE_BYTES = 20_000_000;
+// A file this large or larger is still inventoried (category, size, etc.)
+// but never read for line-count -- keeps content reads bounded.
+const DEFAULT_MAX_FILE_BYTES_FOR_LINE_COUNT = 500_000;
+// Bytes read (at most) when sniffing for a NUL byte to detect binary content
+// for files without a known binary extension.
+const BINARY_SNIFF_BYTES = 512;
+export function scanProjectInventory(targetRoot, options = {}) {
+    const resolvedRoot = path.resolve(targetRoot);
+    const hardSkipFileBytes = options.hardSkipFileBytes ?? DEFAULT_HARD_SKIP_FILE_BYTES;
+    const maxFileBytesForLineCount = options.maxFileBytesForLineCount ?? DEFAULT_MAX_FILE_BYTES_FOR_LINE_COUNT;
+    const warnings = [];
+    const excludedDirCounts = new Map();
+    const files = [];
+    let totalFileCount = 0;
+    let skippedFileCount = 0;
+    let oversizedSkipCount = 0;
+    walk(resolvedRoot);
+    files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    if (oversizedSkipCount > 0) {
+        warnings.push(`Skipped ${oversizedSkipCount} oversized file(s) (>= ${hardSkipFileBytes} bytes): possible generated bundle or binary artifact.`);
+    }
+    const filesByCategory = countByCategory(files);
+    const filesByExtension = countByExtension(files);
+    const filesByLanguage = countByLanguage(files);
+    const filesByRole = countByRole(files);
+    const excludedDirectorySummary = [...excludedDirCounts.entries()]
+        .map(([name, occurrences]) => ({ name, occurrences }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        targetRoot: resolvedRoot,
+        scanRoot: resolvedRoot,
+        totalFileCount,
+        totalScannedFileCount: files.length,
+        skippedFileCount,
+        filesByCategory,
+        filesByExtension,
+        filesByLanguage,
+        filesByRole,
+        packageFiles: files.filter((f) => f.category === "package"),
+        docsFiles: files.filter((f) => f.category === "docs"),
+        sourceFiles: files.filter((f) => f.category === "source"),
+        testFiles: files.filter((f) => f.category === "tests"),
+        scriptFiles: files.filter((f) => f.category === "scripts"),
+        ciFiles: files.filter((f) => f.category === "ci"),
+        excludedDirectorySummary,
+        warnings,
+        files,
+    };
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            warnings.push(`Could not read directory: ${dir} (${err instanceof Error ? err.message : String(err)})`);
+            return;
+        }
+        // Sort entries so traversal order (and therefore file discovery order
+        // before the final sort-by-relativePath) is stable across platforms
+        // regardless of the OS's own readdir ordering.
+        const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of sorted) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (EXCLUDED_DIR_NAMES.has(entry.name)) {
+                    excludedDirCounts.set(entry.name, (excludedDirCounts.get(entry.name) ?? 0) + 1);
+                    continue;
+                }
+                walk(fullPath);
+                continue;
+            }
+            if (!entry.isFile()) {
+                // Skip symlinks and other special entries -- not part of Batch 2 scope.
+                continue;
+            }
+            if (isNoiseFile(entry.name)) {
+                continue;
+            }
+            totalFileCount += 1;
+            let stat;
+            try {
+                stat = fs.statSync(fullPath);
+            }
+            catch (err) {
+                skippedFileCount += 1;
+                warnings.push(`Could not stat file: ${fullPath} (${err instanceof Error ? err.message : String(err)})`);
+                continue;
+            }
+            if (stat.size >= hardSkipFileBytes) {
+                skippedFileCount += 1;
+                oversizedSkipCount += 1;
+                continue;
+            }
+            const relativePath = relativeWithinRoot(resolvedRoot, fullPath);
+            const extension = path.extname(entry.name).toLowerCase();
+            const category = classifyFile(relativePath, entry.name, extension);
+            const language = classifyLanguage(extension);
+            const role = classifyFileRole(relativePath, entry.name, extension, category);
+            const entryResult = {
+                relativePath,
+                normalizedPath: relativePath.toLowerCase(),
+                extension,
+                category,
+                language,
+                role,
+                isGenerated: role === "generated",
+                isBuildOutput: role === "build-output",
+                isVendor: role === "vendor",
+                isReportOutput: role === "report-output",
+                sizeBytes: stat.size,
+                likelyGenerated: category === "generated" || category === "report",
+                likelyConfig: category === "config" || category === "package",
+                likelyDocs: category === "docs",
+                likelyTest: category === "tests",
+                likelySource: category === "source" || category === "scripts",
+            };
+            if (!BINARY_EXTENSIONS.has(extension) && stat.size <= maxFileBytesForLineCount) {
+                const lineCount = tryCountLines(fullPath, warnings);
+                if (lineCount !== undefined) {
+                    entryResult.lineCount = lineCount;
+                }
+            }
+            files.push(entryResult);
+        }
+    }
+}
+function classifyFile(relativePath, basename, extension) {
+    if (PACKAGE_FILE_NAMES.has(basename))
+        return "package";
+    if (relativePath.startsWith(".github/workflows/") && (extension === ".yml" || extension === ".yaml")) {
+        return "ci";
+    }
+    if (isTestFile(relativePath, basename))
+        return "tests";
+    // Top-level scripts/ directory -- classified before generic "source" so
+    // scripts (which are also .ts/.js) land in their own category.
+    if (relativePath.startsWith("scripts/"))
+        return "scripts";
+    if (extension === ".md" || extension === ".mdx" || relativePath.startsWith("docs/"))
+        return "docs";
+    if (isConfigFile(relativePath, basename, extension))
+        return "config";
+    if (isStrayReportFile(basename))
+        return "report";
+    if (extension === ".map")
+        return "generated";
+    if (KNOWN_SOURCE_EXTENSIONS.has(extension))
+        return "source";
+    return "unknown";
+}
+function isTestFile(relativePath, basename) {
+    if (relativePath.startsWith("tests/") || relativePath.includes("/tests/"))
+        return true;
+    return /\.(test|spec)\.[jt]sx?$/.test(basename);
+}
+function isConfigFile(relativePath, basename, extension) {
+    if (/^tsconfig(\..+)?\.json$/.test(basename))
+        return true;
+    if (/^vitest\.config\.[jt]s$/.test(basename) || basename === "vitest.workspace.ts")
+        return true;
+    if (/^\.eslintrc(\..+)?$/.test(basename) || /^eslint\.config\.[jt]s$/.test(basename))
+        return true;
+    if (basename === ".editorconfig" || basename === ".gitignore" || basename === ".npmignore")
+        return true;
+    // Root-level dotfile configs (e.g. .prettierrc, .babelrc) not already
+    // covered above -- deliberately conservative (root-only, not recursive)
+    // to avoid misclassifying dotfiles inside fixture/benchmark projects.
+    if (!relativePath.includes("/") && basename.startsWith("."))
+        return true;
+    if (extension === ".json" && basename.toLowerCase().includes("config"))
+        return true;
+    return false;
+}
+function isStrayReportFile(basename) {
+    return /-security-validation\.(txt|json)$/.test(basename) || /-audit\.(txt|json)$/.test(basename);
+}
+function tryCountLines(fullPath, warnings) {
+    let buffer;
+    try {
+        buffer = fs.readFileSync(fullPath);
+    }
+    catch (err) {
+        warnings.push(`Could not read file for line count: ${fullPath} (${err instanceof Error ? err.message : String(err)})`);
+        return undefined;
+    }
+    const sniffLength = Math.min(buffer.length, BINARY_SNIFF_BYTES);
+    for (let i = 0; i < sniffLength; i++) {
+        if (buffer[i] === 0) {
+            // NUL byte present -- treat as binary, skip line counting.
+            return undefined;
+        }
+    }
+    if (buffer.length === 0)
+        return 0;
+    const text = buffer.toString("utf8");
+    let lines = 1;
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === "\n")
+            lines += 1;
+    }
+    return lines;
+}
+function countByCategory(files) {
+    const counts = Object.fromEntries(INVENTORY_FILE_CATEGORIES.map((c) => [c, 0]));
+    for (const file of files) {
+        counts[file.category] += 1;
+    }
+    return counts;
+}
+function countByLanguage(files) {
+    const counts = Object.fromEntries(NORMALIZED_LANGUAGES.map((l) => [l, 0]));
+    for (const file of files) {
+        counts[file.language] += 1;
+    }
+    return counts;
+}
+function countByRole(files) {
+    const counts = Object.fromEntries(FILE_ROLES.map((r) => [r, 0]));
+    for (const file of files) {
+        counts[file.role] += 1;
+    }
+    return counts;
+}
+function countByExtension(files) {
+    const counts = new Map();
+    for (const file of files) {
+        const key = file.extension || "(none)";
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const sortedEntries = [...counts.entries()].sort(([a], [b]) => a.localeCompare(b));
+    return Object.fromEntries(sortedEntries);
+}

package/dist/src/audits/core/sourceFacts.js

@@ -0,0 +1,17 @@
+// ---------------------------------------------------------------------------
+// v0.3.1 Batch 2 -- normalized source facts model.
+//
+// Purely additive substrate: no concrete language analyzer exists yet (that
+// is Batch 3's TypeScript/JavaScript analyzer), so every SourceFileFacts
+// produced in this batch is either a deterministic fallback (see
+// collectSourceFacts.ts) or a parse-error record. The fact arrays
+// (imports/exports/declarations/references) are always empty in this batch
+// -- the shape exists so Batch 3 can populate them without a type change.
+// ---------------------------------------------------------------------------
+export const SOURCE_FACT_PARSE_STATUSES = [
+    "parsed",
+    "file-level-only",
+    "unsupported",
+    "parse-error",
+    "skipped",
+];