@dailephd/my-dev-kit-lab 0.3.0 → 0.3.2

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

@@ -27,6 +27,112 @@ export const INVENTORY_FILE_CATEGORIES = [
     "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",
@@ -96,6 +202,24 @@ const KNOWN_SOURCE_EXTENSIONS = new Set([
     ".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.
@@ -123,6 +247,8 @@ export function scanProjectInventory(targetRoot, options = {}) {
     }
     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));
@@ -134,6 +260,8 @@ export function scanProjectInventory(targetRoot, options = {}) {
         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"),
@@ -192,11 +320,19 @@ export function scanProjectInventory(targetRoot, options = {}) {
             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",
@@ -220,7 +356,7 @@ function classifyFile(relativePath, basename, extension) {
     if (relativePath.startsWith(".github/workflows/") && (extension === ".yml" || extension === ".yaml")) {
         return "ci";
     }
-    if (isTestFile(relativePath, basename))
+    if (isTestFile(relativePath, basename, extension))
         return "tests";
     // Top-level scripts/ directory -- classified before generic "source" so
     // scripts (which are also .ts/.js) land in their own category.
@@ -238,11 +374,37 @@ function classifyFile(relativePath, basename, extension) {
         return "source";
     return "unknown";
 }
-function isTestFile(relativePath, basename) {
+// v0.3.2 Batch 1 -- conservative pytest naming conventions. Gated to .py so
+// this can never reclassify a non-Python file. "tests/**/*.py" and
+// "**/tests/**/*.py" are already covered by the generic, extension-agnostic
+// check above; only the singular "test/" directory and the test_*.py /
+// *_test.py filename conventions are Python-specific additions here.
+function isPythonTestFile(relativePath, basename) {
+    if (relativePath.startsWith("test/") || relativePath.includes("/test/"))
+        return true;
+    return /^test_.*\.py$/.test(basename) || /^.*_test\.py$/.test(basename);
+}
+function isTestFile(relativePath, basename, extension) {
     if (relativePath.startsWith("tests/") || relativePath.includes("/tests/"))
         return true;
-    return /\.(test|spec)\.[jt]sx?$/.test(basename);
+    if (/\.(test|spec)\.[jt]sx?$/.test(basename))
+        return true;
+    if (extension === ".py" && isPythonTestFile(relativePath, basename))
+        return true;
+    return false;
 }
+// v0.3.2 Batch 1 -- recognized Python project/config metadata filenames.
+// Matched by basename only (same convention as PACKAGE_FILE_NAMES above),
+// not restricted to root, since these are specific enough not to collide
+// with unrelated fixture/benchmark content. Deliberately narrow: does not
+// match arbitrary *.toml/*.ini/*.txt files, only these exact names.
+const PYTHON_PROJECT_METADATA_FILE_NAMES = new Set([
+    "pyproject.toml",
+    "requirements.txt",
+    "setup.cfg",
+    "tox.ini",
+    "pytest.ini",
+]);
 function isConfigFile(relativePath, basename, extension) {
     if (/^tsconfig(\..+)?\.json$/.test(basename))
         return true;
@@ -252,6 +414,12 @@ function isConfigFile(relativePath, basename, extension) {
         return true;
     if (basename === ".editorconfig" || basename === ".gitignore" || basename === ".npmignore")
         return true;
+    // v0.3.2 Batch 1 -- setup.py has a .py extension and would otherwise fall
+    // through to the generic KNOWN_SOURCE_EXTENSIONS "source" classification
+    // below; the other names have no source-extension conflict but are listed
+    // here for the same "project metadata, not source" reasoning.
+    if (basename === "setup.py" || PYTHON_PROJECT_METADATA_FILE_NAMES.has(basename))
+        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.
@@ -297,6 +465,20 @@ function countByCategory(files) {
     }
     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) {

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

@@ -0,0 +1,328 @@
+// ---------------------------------------------------------------------------
+// v0.3.2 Batch 1 -- conservative, dependency-free Python source analyzer.
+//
+// There is no Python parser available in this Node/TypeScript project, and
+// per this batch's own scope this analyzer must not add a new parser
+// dependency. Facts are therefore extracted with a deliberately narrow,
+// line-oriented regex scan -- not a real tokenizer, not an AST, and not a
+// syntax validator. This is the single-file, best-effort analogue of
+// typescriptJavaScriptAnalyzer.ts's AST walk: same LanguageAnalyzer contract,
+// same SourceFileFacts shape, same size-bounding philosophy, but confidence
+// is necessarily lower since nothing here proves the file is syntactically
+// valid Python.
+//
+// What this DOES extract (see requirements 3 of the batch spec):
+//   - import module[, module2][ as alias]
+//   - from [.[.]]module import name[ as alias][, ...]  (single physical line)
+//   - from module import *
+//   - module-level `def`/`async def`/`class` declarations
+//   - class-body method declarations, via a simple indentation-based scope
+//     stack (not scope-accurate for deeply nested blocks, just "is this def
+//     more indented than the nearest enclosing class line")
+//   - a single-line `__all__ = [...]`/`(...)` string list, used to set
+//     `exported` precisely when present
+//
+// What this explicitly does NOT do (see requirements 3's "do not implement"
+// list): type checking, full AST/semantic resolution, virtualenv/dependency
+// resolution, runtime or dynamic import resolution, decorator/metaclass/
+// fixture semantics, or any claim of dead-code/duplicate-implementation
+// proof. `__import__(...)`/`importlib.import_module(...)` calls are recorded
+// only as an informational diagnostic, never as a resolved import fact.
+// ---------------------------------------------------------------------------
+export const PYTHON_ANALYZER_ID = "python-analyzer";
+const SUPPORTED_EXTENSIONS = [".py"];
+// Mirrors typescriptJavaScriptAnalyzer.ts's MAX_ANALYZABLE_BYTES bound and
+// reasoning -- a large file is not worth line-scanning, and stays at
+// file-level-only rather than file-level-only masquerading as parsed.
+const MAX_ANALYZABLE_BYTES = 1_000_000;
+const IMPORT_LINE_PATTERN = /^\s*import\s+(.+)$/;
+const FROM_IMPORT_LINE_PATTERN = /^\s*from\s+(\.{0,2}[\w.]*)\s+import\s+(.+)$/;
+const DEF_LINE_PATTERN = /^(\s*)(?:async\s+def|def)\s+([A-Za-z_]\w*)\s*\(/;
+const CLASS_LINE_PATTERN = /^(\s*)class\s+([A-Za-z_]\w*)\s*[:(]/;
+const ALL_ASSIGNMENT_PATTERN = /^\s*__all__\s*=\s*[[(](.*)$/;
+const DYNAMIC_IMPORT_PATTERN = /\b(?:__import__\s*\(|importlib\.import_module\s*\()/;
+const QUOTED_NAME_PATTERN = /(['"])((?:(?!\1).)*)\1/g;
+export const PYTHON_ANALYZER = {
+    id: PYTHON_ANALYZER_ID,
+    supportedLanguages: ["python"],
+    supportedExtensions: SUPPORTED_EXTENSIONS,
+    analyzeFile,
+};
+function analyzeFile(input) {
+    const { relativePath, language, role, content, inventoryEntry } = input;
+    if (Buffer.byteLength(content, "utf8") > MAX_ANALYZABLE_BYTES) {
+        return {
+            relativePath,
+            language,
+            role,
+            parseStatus: "file-level-only",
+            analyzerId: PYTHON_ANALYZER_ID,
+            lineCount: inventoryEntry.lineCount,
+            imports: [],
+            exports: [],
+            declarations: [],
+            references: [],
+            diagnostics: [
+                {
+                    severity: "info",
+                    code: "file-too-large-for-analysis",
+                    message: `File exceeds the ${MAX_ANALYZABLE_BYTES}-byte analyzer bound; only inventory-level facts are available.`,
+                    path: relativePath,
+                    analyzerId: PYTHON_ANALYZER_ID,
+                },
+            ],
+        };
+    }
+    const diagnostics = [];
+    const { logical, hadUnterminatedTripleQuote } = buildLogicalLines(content);
+    const imports = [];
+    for (let i = 0; i < logical.length; i++) {
+        const line = logical[i];
+        const lineNumber = i + 1;
+        if (parseFromImportLine(line, lineNumber, imports, diagnostics, relativePath))
+            continue;
+        parseImportLine(line, lineNumber, imports);
+    }
+    const exportedSet = scanAllExport(logical);
+    const declarations = scanDeclarations(logical, exportedSet);
+    scanDynamicImportPatterns(logical, diagnostics, relativePath);
+    const exports = exportedSet ? [...exportedSet].map((name) => ({ name, kind: "named" })) : [];
+    if (hadUnterminatedTripleQuote) {
+        diagnostics.push({
+            severity: "error",
+            code: "unterminated-triple-quoted-string",
+            message: "File appears to contain an unterminated triple-quoted string (unbalanced \"\"\"/''' delimiters); facts from this best-effort scan may be incomplete.",
+            path: relativePath,
+            analyzerId: PYTHON_ANALYZER_ID,
+        });
+    }
+    const parseStatus = hadUnterminatedTripleQuote ? "parse-error" : "parsed";
+    return {
+        relativePath,
+        language,
+        role,
+        parseStatus,
+        analyzerId: PYTHON_ANALYZER_ID,
+        lineCount: inventoryEntry.lineCount,
+        imports,
+        exports,
+        declarations,
+        references: [],
+        diagnostics,
+    };
+}
+// ---------------------------------------------------------------------------
+// Comment/triple-quoted-string stripping (heuristic, not a tokenizer).
+// ---------------------------------------------------------------------------
+// Strips a trailing `# comment`, respecting simple single/double-quoted
+// strings on the same line (so `x = "a # b"` is not truncated at the `#`
+// inside the string). Does not understand triple-quoted strings -- those are
+// handled one level up by buildLogicalLines(), which never passes a
+// mid-triple-quote-block line to this function.
+function stripLineComment(line) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === "\\" && (inSingle || inDouble)) {
+            i++;
+            continue;
+        }
+        if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (ch === "#" && !inSingle && !inDouble)
+            return line.slice(0, i);
+    }
+    return line;
+}
+// Produces one "logical" line per physical line: comments stripped, and any
+// content inside a triple-quoted string block (`"""..."""` / `'''...'''`)
+// blanked out so it can never be misread as an import/def/class statement.
+// Deliberately narrow: only tracks a single open triple-quote marker at a
+// time and does not handle more than one triple-quoted segment opening and
+// closing on the same physical line.
+function buildLogicalLines(content) {
+    const rawLines = content.split(/\r\n|\r|\n/);
+    const logical = [];
+    let openQuote = null;
+    for (const rawLine of rawLines) {
+        if (openQuote) {
+            const closeIdx = rawLine.indexOf(openQuote);
+            if (closeIdx === -1) {
+                logical.push("");
+                continue;
+            }
+            openQuote = null;
+            logical.push(stripLineComment(rawLine.slice(closeIdx + 3)));
+            continue;
+        }
+        const stripped = stripLineComment(rawLine);
+        const tripleMatch = stripped.match(/"""|'''/);
+        if (!tripleMatch) {
+            logical.push(stripped);
+            continue;
+        }
+        const marker = tripleMatch[0];
+        const firstIdx = stripped.indexOf(marker);
+        const secondIdx = stripped.indexOf(marker, firstIdx + marker.length);
+        if (secondIdx === -1) {
+            logical.push(stripped.slice(0, firstIdx));
+            openQuote = marker;
+        }
+        else {
+            logical.push(stripped.slice(0, firstIdx) + stripped.slice(secondIdx + marker.length));
+        }
+    }
+    return { logical, hadUnterminatedTripleQuote: openQuote !== null };
+}
+function leadingWhitespaceCount(line) {
+    let count = 0;
+    for (const ch of line) {
+        if (ch === " " || ch === "\t")
+            count += 1;
+        else
+            break;
+    }
+    return count;
+}
+// ---------------------------------------------------------------------------
+// Imports.
+// ---------------------------------------------------------------------------
+function parseImportLine(line, lineNumber, imports) {
+    const match = line.match(IMPORT_LINE_PATTERN);
+    if (!match)
+        return;
+    for (const rawSegment of match[1].split(",")) {
+        const segment = rawSegment.trim();
+        if (!segment)
+            continue;
+        const asMatch = segment.match(/^([\w.]+)\s+as\s+(\w+)$/);
+        if (asMatch) {
+            imports.push({ source: asMatch[1], kind: "static", importedNames: [asMatch[2]], line: lineNumber });
+        }
+        else {
+            imports.push({ source: segment, kind: "static", line: lineNumber });
+        }
+    }
+}
+function parseFromImportLine(line, lineNumber, imports, diagnostics, relativePath) {
+    const match = line.match(FROM_IMPORT_LINE_PATTERN);
+    if (!match)
+        return false;
+    const modulePath = match[1] || ".";
+    let namesPart = match[2].trim();
+    if (namesPart.startsWith("(") && namesPart.endsWith(")")) {
+        namesPart = namesPart.slice(1, -1);
+    }
+    else if (namesPart.startsWith("(")) {
+        // Multi-line parenthesized from-import list -- this single-line scanner
+        // does not follow continuation lines. Recorded as a diagnostic rather
+        // than silently dropped or guessed at.
+        diagnostics.push({
+            severity: "info",
+            code: "multiline-from-import-unsupported",
+            message: "Multi-line parenthesized from-import list is not analyzed by this conservative single-line scanner.",
+            path: relativePath,
+            analyzerId: PYTHON_ANALYZER_ID,
+        });
+        return true;
+    }
+    if (namesPart === "*") {
+        imports.push({ source: modulePath, kind: "static", line: lineNumber });
+        return true;
+    }
+    const importedNames = [];
+    for (const rawSegment of namesPart.split(",")) {
+        const segment = rawSegment.trim();
+        if (!segment)
+            continue;
+        const asMatch = segment.match(/^(\w+)\s+as\s+(\w+)$/);
+        importedNames.push(asMatch ? asMatch[2] : segment);
+    }
+    imports.push({
+        source: modulePath,
+        kind: "static",
+        line: lineNumber,
+        ...(importedNames.length > 0 ? { importedNames } : {}),
+    });
+    return true;
+}
+// ---------------------------------------------------------------------------
+// __all__ (optional, single-line only).
+// ---------------------------------------------------------------------------
+function scanAllExport(logical) {
+    for (const line of logical) {
+        const match = line.match(ALL_ASSIGNMENT_PATTERN);
+        if (!match)
+            continue;
+        const names = [...match[1].matchAll(QUOTED_NAME_PATTERN)].map((m) => m[2]);
+        if (names.length > 0)
+            return new Set(names);
+    }
+    return null;
+}
+function isExported(name, exportedSet) {
+    if (exportedSet)
+        return exportedSet.has(name);
+    // Conservative convention-based heuristic when no __all__ is present: a
+    // leading underscore is Python's own "not public" signal. This is a
+    // heuristic, not a semantic guarantee -- see module header comment.
+    return !name.startsWith("_");
+}
+// ---------------------------------------------------------------------------
+// Declarations (functions, async functions, classes, class methods).
+// ---------------------------------------------------------------------------
+function scanDeclarations(logical, exportedSet) {
+    const declarations = [];
+    // Indent levels of currently-open `class` blocks, outermost first. A line
+    // whose indentation drops to or below the top of this stack has exited
+    // that class body.
+    const classIndentStack = [];
+    for (let i = 0; i < logical.length; i++) {
+        const line = logical[i];
+        if (line.trim().length === 0)
+            continue;
+        const lineNumber = i + 1;
+        const indent = leadingWhitespaceCount(line);
+        while (classIndentStack.length > 0 && indent <= classIndentStack[classIndentStack.length - 1]) {
+            classIndentStack.pop();
+        }
+        const classMatch = line.match(CLASS_LINE_PATTERN);
+        if (classMatch) {
+            const name = classMatch[2];
+            declarations.push({ name, kind: "class", exported: isExported(name, exportedSet), line: lineNumber });
+            classIndentStack.push(indent);
+            continue;
+        }
+        const defMatch = line.match(DEF_LINE_PATTERN);
+        if (defMatch) {
+            const name = defMatch[2];
+            const isMethod = classIndentStack.length > 0 && indent > classIndentStack[classIndentStack.length - 1];
+            declarations.push({
+                name,
+                kind: isMethod ? "method" : "function",
+                // Methods are not tracked against __all__/underscore-export
+                // semantics -- __all__ only ever names module-level symbols in
+                // real Python, so claiming a method is "exported" would overclaim.
+                exported: isMethod ? false : isExported(name, exportedSet),
+                line: lineNumber,
+            });
+        }
+    }
+    return declarations;
+}
+function scanDynamicImportPatterns(logical, diagnostics, relativePath) {
+    for (const line of logical) {
+        if (!DYNAMIC_IMPORT_PATTERN.test(line))
+            continue;
+        diagnostics.push({
+            severity: "info",
+            code: "dynamic-import-pattern-unsupported",
+            message: "Detected a __import__/importlib.import_module call; dynamic imports are not resolved as import facts.",
+            path: relativePath,
+            analyzerId: PYTHON_ANALYZER_ID,
+        });
+    }
+}

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

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+const PYPROJECT_PROJECT_NAME_PATTERN = /^\s*name\s*=\s*["']([^"']+)["']\s*$/m;
+const PYPROJECT_PYTEST_SECTION_PATTERN = /^\s*\[tool\.pytest\.ini_options\]\s*$/m;
+const SETUP_CFG_PYTEST_SECTION_PATTERN = /^\s*\[tool:pytest\]\s*$/m;
+const INI_SECTION_HEADER_PATTERN = /^\s*\[([^\]]+)\]\s*$/;
+const INI_NAME_KEY_PATTERN = /^\s*name\s*=\s*(.+?)\s*$/;
+// Extracts the `name = ...` value from a setup.cfg-style [metadata] section
+// via a simple line scan (no INI parser dependency) -- stops at the next
+// "[section]" header or end of file.
+function extractSetupCfgProjectName(content) {
+    const lines = content.split(/\r\n|\r|\n/);
+    let inMetadataSection = false;
+    for (const line of lines) {
+        const sectionMatch = line.match(INI_SECTION_HEADER_PATTERN);
+        if (sectionMatch) {
+            inMetadataSection = sectionMatch[1].trim().toLowerCase() === "metadata";
+            continue;
+        }
+        if (!inMetadataSection)
+            continue;
+        const nameMatch = line.match(INI_NAME_KEY_PATTERN);
+        if (nameMatch)
+            return nameMatch[1];
+    }
+    return null;
+}
+export function collectPythonProjectMetadata(targetRoot, inventory) {
+    const warnings = [];
+    const knownPaths = new Set(inventory.files.map((f) => f.relativePath));
+    const has = (name) => knownPaths.has(name);
+    const hasPyprojectToml = has("pyproject.toml");
+    const hasRequirementsTxt = has("requirements.txt");
+    const hasSetupPy = has("setup.py");
+    const hasSetupCfg = has("setup.cfg");
+    const hasToxIni = has("tox.ini");
+    const hasPytestIni = has("pytest.ini");
+    let projectName = null;
+    let pytestSectionDetected = false;
+    if (hasPyprojectToml) {
+        const content = readSafely(targetRoot, "pyproject.toml", warnings);
+        if (content !== null) {
+            const nameMatch = content.match(PYPROJECT_PROJECT_NAME_PATTERN);
+            if (nameMatch)
+                projectName = nameMatch[1];
+            if (PYPROJECT_PYTEST_SECTION_PATTERN.test(content))
+                pytestSectionDetected = true;
+        }
+    }
+    if (hasSetupCfg) {
+        const content = readSafely(targetRoot, "setup.cfg", warnings);
+        if (content !== null) {
+            if (projectName === null) {
+                projectName = extractSetupCfgProjectName(content);
+            }
+            if (SETUP_CFG_PYTEST_SECTION_PATTERN.test(content))
+                pytestSectionDetected = true;
+        }
+    }
+    return {
+        hasPyprojectToml,
+        hasRequirementsTxt,
+        hasSetupPy,
+        hasSetupCfg,
+        hasToxIni,
+        hasPytestIni,
+        hasPytestConfiguration: hasPytestIni || pytestSectionDetected,
+        projectName,
+        warnings,
+    };
+}
+function readSafely(targetRoot, relativePath, warnings) {
+    try {
+        return fs.readFileSync(path.join(targetRoot, relativePath), "utf8");
+    }
+    catch (err) {
+        warnings.push(`Could not read ${relativePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}

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",
+];