agent-rules-init 0.3.0 → 0.4.0

package/dist/core/repo-facts.js

@@ -1,21 +1,55 @@
 import path from "node:path";
 import { parse } from "yaml";
 import { UI } from "./i18n.js";
+import { selectCanonicalCommands } from "./canonical-commands.js";
 const NPM_DIRECT_LIFECYCLE = new Set(["test", "start", "stop", "restart"]);
-export function extractNpmCommands(signals) {
-    const scripts = signals.packageJson?.scripts ?? {};
+export function extractJsPackageCommands(signals) {
     const entries = [];
-    for (const [name, body] of Object.entries(scripts)) {
-        if (typeof body !== "string" || body.trim() === "")
-            continue;
-        entries.push({
-            source: "npm",
-            invocation: NPM_DIRECT_LIFECYCLE.has(name) ? `npm ${name}` : `npm run ${name}`,
-            detail: body.trim(),
-        });
+    const locatedManifests = signals.packageJsons ?? [];
+    const hasLocatedManifests = locatedManifests.length > 0;
+    const manifests = hasLocatedManifests
+        ? locatedManifests
+        : signals.packageJson
+            ? [{ ...signals.packageJson, path: "package.json" }]
+            : [];
+    for (const manifest of manifests) {
+        const packageDir = path.posix.dirname(manifest.path);
+        const manager = manifest.packageManager ?? signals.packageJson?.packageManager ?? "npm";
+        for (const [name, body] of Object.entries(manifest.scripts)) {
+            if (typeof body !== "string" || body.trim() === "")
+                continue;
+            entries.push({
+                source: manager,
+                invocation: jsScriptInvocation(manager, packageDir, name),
+                detail: body.trim(),
+                ...(hasLocatedManifests ? { manifestPath: manifest.path } : {}),
+            });
+        }
     }
     return entries;
 }
+/** @deprecated Conservado como alias de API; también devuelve comandos pnpm/Yarn/Bun. */
+export const extractNpmCommands = extractJsPackageCommands;
+function jsScriptInvocation(manager, packageDir, script) {
+    const name = quoteShellArg(script);
+    if (manager === "npm") {
+        const prefix = packageDir === "." ? "npm" : `npm --prefix ${quoteShellArg(packageDir)}`;
+        return NPM_DIRECT_LIFECYCLE.has(script) ? `${prefix} ${name}` : `${prefix} run ${name}`;
+    }
+    if (manager === "pnpm") {
+        const prefix = packageDir === "." ? "pnpm" : `pnpm --dir ${quoteShellArg(packageDir)}`;
+        return NPM_DIRECT_LIFECYCLE.has(script) ? `${prefix} ${name}` : `${prefix} run ${name}`;
+    }
+    if (manager === "yarn") {
+        const prefix = packageDir === "." ? "yarn" : `yarn --cwd ${quoteShellArg(packageDir)}`;
+        return `${prefix} run ${name}`;
+    }
+    const prefix = packageDir === "." ? "bun" : `bun --cwd ${quoteShellArg(packageDir)}`;
+    return `${prefix} run ${name}`;
+}
+function quoteShellArg(value) {
+    return /\s/.test(value) ? JSON.stringify(value) : value;
+}
 export function extractMakeTargets(signals) {
     const makefile = signals.makefile;
     if (!makefile)
@@ -178,9 +212,190 @@ export function extractStructure(signals, lang) {
         return note ? { dir: `${dir}/`, note } : { dir: `${dir}/` };
     });
 }
+const TEST_DIR_NAMES = new Set(["test", "tests", "spec", "specs", "__tests__"]);
+const MEANINGFUL_TEST_CHILDREN = new Set(["acceptance", "integration", "unit", "e2e"]);
+const AUXILIARY_FACT_DIRS = new Set([
+    "docs", "doc", "tools", "tool", "scripts", "script", "examples", "example",
+    "benchmark", "benchmarks", "fixture", "fixtures",
+]);
+function isAuxiliaryFactPath(file) {
+    return file.split(/[\\/]/).some((segment) => AUXILIARY_FACT_DIRS.has(segment.toLowerCase()));
+}
+export function detectTestDirs(files) {
+    const dirs = new Set();
+    for (const file of files) {
+        const segments = file.split(/[\\/]/).slice(0, -1);
+        for (let i = 0; i < segments.length; i++) {
+            if (TEST_DIR_NAMES.has(segments[i].toLowerCase())) {
+                dirs.add(segments.slice(0, i + 1).join("/") + "/");
+                // Solo conserva sublayouts inequívocos. Directorios como tests/static o
+                // tests/templates suelen ser fixtures, no ubicaciones independientes de tests.
+                const child = segments[i + 1]?.toLowerCase();
+                const languageLayout = segments[0]?.toLowerCase() === "src" && segments[1]?.toLowerCase() === "test";
+                if (child && (languageLayout || MEANINGFUL_TEST_CHILDREN.has(child))) {
+                    dirs.add(segments.slice(0, i + 2).join("/") + "/");
+                }
+                break;
+            }
+        }
+    }
+    return [...dirs].sort();
+}
+export function detectEntrypoints(signals) {
+    const out = [];
+    if (signals.packageJson?.main) {
+        out.push({ label: "main", target: signals.packageJson.main, source: "package.json" });
+    }
+    const scriptsSection = signals.pyprojectToml?.match(/\[project\.scripts\]([\s\S]*?)(?:\n\[|$)/)?.[1];
+    if (scriptsSection) {
+        for (const match of scriptsSection.matchAll(/^\s*([\w.-]+)\s*=\s*["']([^"']+)["']/gm)) {
+            out.push({ label: match[1], target: match[2], source: "pyproject.toml" });
+        }
+    }
+    return out;
+}
+function evidencePath(file) {
+    return file.split(path.sep).join("/");
+}
+export function extractArchitectureFacts(signals, lang, testDirs = detectTestDirs(signals.files.filter((file) => !isAuxiliaryFactPath(file))), entrypoints = detectEntrypoints(signals)) {
+    const facts = [];
+    const normalized = signals.files.filter((file) => !isAuxiliaryFactPath(file)).map(evidencePath);
+    const add = (fact) => facts.push({ ...fact, scope: ".", confidence: "high" });
+    if (entrypoints.length > 0) {
+        const rendered = entrypoints.map((entry) => `${entry.label} -> ${entry.target}`).join(", ");
+        add({
+            kind: "entrypoint",
+            statement: lang === "es" ? `Puntos de entrada declarados: ${rendered}.` : `Declared entry points: ${rendered}.`,
+            evidence: [...new Set(entrypoints.map((entry) => entry.source))],
+        });
+    }
+    if (testDirs.length > 0) {
+        const testEvidence = [...new Set(testDirs.map((dir) => {
+                const directory = dir.replace(/\/$/, "");
+                return signals.hasDir(directory) ? dir : normalized.find((file) => file.startsWith(dir));
+            }).filter((f) => Boolean(f)))];
+        add({
+            kind: "tests",
+            statement: lang === "es"
+                ? `Los tests se colocan en ${testDirs.join(", ")}.`
+                : `Tests are placed under ${testDirs.join(", ")}.`,
+            evidence: testEvidence,
+        });
+    }
+    const sourceRoots = ["src", "lib"].filter((dir) => signals.hasDir(dir) || normalized.some((file) => file.startsWith(`${dir}/`)));
+    const sourceLocations = sourceRoots.flatMap((dir) => dir === "src" && signals.hasDir("src/main") ? ["src/main/"] : [`${dir}/`]);
+    if (sourceLocations.length > 0) {
+        add({
+            kind: "source-layout",
+            statement: lang === "es"
+                ? `El código principal vive en ${sourceLocations.join(", ")}.`
+                : `Primary source code lives under ${sourceLocations.join(", ")}.`,
+            evidence: sourceLocations.map((location) => {
+                const directory = location.replace(/\/$/, "");
+                return signals.hasDir(directory) ? location : normalized.find((file) => file.startsWith(location));
+            }).filter(Boolean),
+        });
+    }
+    const layerPatterns = [
+        ["controller", /(?:^|\/)(?:controllers?)(?:\/|$)/i],
+        ["service", /(?:^|\/)(?:services?)(?:\/|$)/i],
+        ["repository", /(?:^|\/)(?:repositories|repository)(?:\/|$)/i],
+    ];
+    const layers = layerPatterns.map(([name, pattern]) => ({ name, file: normalized.find((file) => pattern.test(file)) }));
+    if (layers.every((layer) => layer.file)) {
+        add({
+            kind: "layers",
+            statement: lang === "es"
+                ? "El repositorio separa controller, service y repository en capas distintas."
+                : "The repository separates controller, service and repository into distinct layers.",
+            evidence: layers.map((layer) => layer.file),
+        });
+    }
+    const workspaceManifests = (signals.packageJsons ?? []).filter((manifest) => manifest.path !== "package.json");
+    if (workspaceManifests.length > 0) {
+        add({
+            kind: "workspace",
+            statement: lang === "es"
+                ? `El workspace contiene ${workspaceManifests.length} paquete(s) JavaScript/TypeScript anidado(s).`
+                : `The workspace contains ${workspaceManifests.length} nested JavaScript/TypeScript package(s).`,
+            evidence: workspaceManifests.map((manifest) => manifest.path),
+        });
+    }
+    return facts;
+}
+function uniqueConfigValue(content, key) {
+    const values = [...content.matchAll(new RegExp(`^\\s*${key}\\s*=\\s*([^#;\\r\\n]+)`, "gmi"))]
+        .map((match) => match[1].trim().toLowerCase());
+    const unique = [...new Set(values)];
+    return unique.length === 1 ? unique[0] : undefined;
+}
+export function extractConventionFacts(signals, lang) {
+    const facts = [];
+    const rootFiles = (signals.guidanceFiles ?? []).filter((file) => !evidencePath(file.path).includes("/"));
+    const get = (name) => rootFiles.find((file) => file.path.toLowerCase() === name.toLowerCase())?.content;
+    const add = (fact) => facts.push({ ...fact, scope: ".", confidence: "high" });
+    const editorConfig = get(".editorconfig");
+    if (editorConfig) {
+        const style = uniqueConfigValue(editorConfig, "indent_style");
+        const rawSize = uniqueConfigValue(editorConfig, "indent_size");
+        const size = rawSize && /^\d+$/.test(rawSize) ? rawSize : undefined;
+        if (style)
+            add({
+                kind: "formatting",
+                statement: lang === "es"
+                    ? `La indentación usa ${style === "space" ? "espacios" : style === "tab" ? "tabuladores" : style}${size ? ` con tamaño ${size}` : ""}.`
+                    : `Indentation uses ${style === "space" ? "spaces" : style === "tab" ? "tabs" : style}${size ? ` with size ${size}` : ""}.`,
+                evidence: [".editorconfig"],
+            });
+        const finalNewline = uniqueConfigValue(editorConfig, "insert_final_newline");
+        if (finalNewline === "true")
+            add({
+                kind: "formatting",
+                statement: lang === "es" ? "Los archivos deben terminar con una línea nueva." : "Files must end with a final newline.",
+                evidence: [".editorconfig"],
+            });
+    }
+    const tsconfig = get("tsconfig.json");
+    if (tsconfig && /["']strict["']\s*:\s*true\b/i.test(tsconfig))
+        add({
+            kind: "typescript",
+            statement: lang === "es" ? "TypeScript tiene activado el modo strict." : "TypeScript strict mode is enabled.",
+            evidence: ["tsconfig.json"],
+        });
+    const pyproject = get("pyproject.toml");
+    if (pyproject) {
+        for (const tool of ["ruff", "black"]) {
+            const section = pyproject.match(new RegExp(`(?:^|\\n)\\[tool\\.${tool}\\]([\\s\\S]*?)(?:\\n\\[|$)`, "i"))?.[1];
+            const lineLength = section?.match(/(?:^|\n)\s*line-length\s*=\s*(\d+)/i)?.[1];
+            if (lineLength)
+                add({
+                    kind: "python-style",
+                    statement: lang === "es"
+                        ? `${tool} configura una longitud máxima de línea de ${lineLength}.`
+                        : `${tool} configures a maximum line length of ${lineLength}.`,
+                    evidence: ["pyproject.toml"],
+                });
+        }
+    }
+    const contributing = get("CONTRIBUTING.md");
+    if (contributing) {
+        const directives = contributing.split(/\r?\n/)
+            .map((line) => line.match(/^\s*[-*]\s+(.{1,180})$/)?.[1]?.trim())
+            .filter((line) => Boolean(line))
+            .filter((line) => /\b(?:must|should|required|do not|don't|run|use|follow|debe|debes|ejecuta|usa|sigue|no añadas)\b/i.test(line))
+            .slice(0, 5);
+        for (const directive of directives)
+            add({
+                kind: "contributing",
+                statement: directive,
+                evidence: ["CONTRIBUTING.md"],
+            });
+    }
+    return facts;
+}
 export function buildRepoFacts(signals, lang) {
     const allCommands = [
-        ...extractNpmCommands(signals),
+        ...extractJsPackageCommands(signals),
         ...extractComposerCommands(signals),
         ...extractMakeTargets(signals),
         ...extractMixAliases(signals),
@@ -188,11 +403,18 @@ export function buildRepoFacts(signals, lang) {
     ];
     const { kept, omitted } = filterCommands(allCommands);
     const { commands: ciCommands, omittedCount: omittedCiCount } = extractCiCommands(signals);
+    const testDirs = detectTestDirs(signals.files.filter((file) => !isAuxiliaryFactPath(file)));
+    const entrypoints = detectEntrypoints(signals);
     return {
         commands: kept,
         omittedCommands: omitted,
         structure: extractStructure(signals, lang),
         ciCommands,
         omittedCiCount,
+        canonical: selectCanonicalCommands(signals, kept, ciCommands),
+        testDirs,
+        entrypoints,
+        architectureFacts: extractArchitectureFacts(signals, lang, testDirs, entrypoints),
+        conventionFacts: extractConventionFacts(signals, lang),
     };
 }

package/dist/core/scanner.js

@@ -1,6 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
-const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".venv", "__pycache__"]);
+const IGNORED_DIRS = new Set([
+    "node_modules", ".git", ".hg", ".svn",
+    "dist", "build", "out", "target", "coverage", "vendor",
+    ".venv", "venv", ".tox", "__pycache__",
+    ".next", ".nuxt", ".svelte-kit", ".turbo", ".cache",
+    ".gradle", ".dart_tool",
+]);
 const MAX_DEPTH = 4;
 function walk(rootPath) {
     const results = [];
@@ -14,6 +20,9 @@ function walk(rootPath) {
         catch {
             return;
         }
+        // Filesystem enumeration order is not guaranteed. Keep discovery stable so
+        // precedence-sensitive facts (for example, the first CI command) are reproducible.
+        entries.sort((a, b) => a.name.localeCompare(b.name));
         for (const entry of entries) {
             if (entry.isDirectory()) {
                 if (IGNORED_DIRS.has(entry.name))
@@ -21,6 +30,8 @@ function walk(rootPath) {
                 recurse(path.join(dir, entry.name), depth + 1);
             }
             else {
+                if (entry.name.includes(".generated."))
+                    continue;
                 results.push(path.relative(rootPath, path.join(dir, entry.name)));
             }
         }
@@ -43,6 +54,56 @@ function readJsonIfExists(filePath) {
         return undefined;
     }
 }
+function toPackageJsonManifest(raw, relativePath) {
+    return {
+        path: relativePath.split(path.sep).join("/"),
+        name: raw.name,
+        main: typeof raw.main === "string" ? raw.main : undefined,
+        dependencies: raw.dependencies ?? {},
+        devDependencies: raw.devDependencies ?? {},
+        scripts: raw.scripts ?? {},
+        moduleType: raw.type === "module" ? "module" : "commonjs",
+        packageManager: parsePackageManager(raw.packageManager),
+    };
+}
+function parsePackageManager(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const name = value.trim().split("@")[0].toLowerCase();
+    return name === "npm" || name === "pnpm" || name === "yarn" || name === "bun" ? name : undefined;
+}
+const LOCK_MANAGERS = {
+    "package-lock.json": "npm",
+    "npm-shrinkwrap.json": "npm",
+    "pnpm-lock.yaml": "pnpm",
+    "yarn.lock": "yarn",
+    "bun.lock": "bun",
+    "bun.lockb": "bun",
+};
+function managerFromClosestLock(manifestPath, normalizedFiles) {
+    let dir = path.posix.dirname(manifestPath.split(path.sep).join("/"));
+    while (true) {
+        for (const [lockName, manager] of Object.entries(LOCK_MANAGERS)) {
+            const candidate = dir === "." ? lockName : `${dir}/${lockName}`;
+            if (normalizedFiles.has(candidate))
+                return manager;
+        }
+        if (dir === ".")
+            return undefined;
+        dir = path.posix.dirname(dir);
+    }
+}
+function managerFromClosestDeclaration(manifestPath, declarations) {
+    let dir = path.posix.dirname(manifestPath);
+    while (true) {
+        const manager = declarations.get(dir);
+        if (manager)
+            return manager;
+        if (dir === ".")
+            return undefined;
+        dir = path.posix.dirname(dir);
+    }
+}
 function readTextIfExists(filePath) {
     if (!fs.existsSync(filePath))
         return undefined;
@@ -76,6 +137,8 @@ const NON_PROJECT_DIRS = new Set([
     "example",
     "benchmark",
     "benchmarks",
+    "fixture",
+    "fixtures",
 ]);
 function isUnderNonProjectDir(relativePath) {
     const segments = relativePath.split(path.sep).slice(0, -1);
@@ -105,17 +168,45 @@ function pickShallowest(paths) {
 export function scanRepo(rootPath) {
     const files = walk(rootPath);
     const fileSet = new Set(files.map((f) => f.split(path.sep).join("/")));
-    const packageJsonPath = findFirst(files, "package.json");
-    const rawPackageJson = packageJsonPath
-        ? readJsonIfExists(path.join(rootPath, packageJsonPath))
-        : undefined;
-    const packageJson = rawPackageJson
+    // Keep every project package manifest, not only the root workspace manifest. Root
+    // package.json files are often workspace glue and contain none of the dependencies
+    // that reveal React/Vitest/etc. Manifests under docs/examples/tooling are excluded to
+    // avoid treating auxiliary demos, fixtures and documentation builds as the project.
+    const packageJsonPaths = files.filter((f) => path.basename(f) === "package.json" && !isUnderNonProjectDir(f));
+    const packageJsons = packageJsonPaths
+        .map((relativePath) => {
+        const raw = readJsonIfExists(path.join(rootPath, relativePath));
+        return raw ? toPackageJsonManifest(raw, relativePath) : undefined;
+    })
+        .filter((manifest) => manifest !== undefined)
+        .sort((a, b) => {
+        const depth = a.path.split("/").length - b.path.split("/").length;
+        return depth || a.path.localeCompare(b.path);
+    });
+    const declaredManagers = new Map(packageJsons
+        .filter((manifest) => manifest.packageManager !== undefined)
+        .map((manifest) => [path.posix.dirname(manifest.path), manifest.packageManager]));
+    // A nested lock takes precedence over an ancestor workspace declaration because it
+    // denotes an independently installed package. Both lookups are O(path depth).
+    for (const manifest of packageJsons) {
+        if (manifest.packageManager)
+            continue;
+        manifest.packageManager =
+            managerFromClosestLock(manifest.path, fileSet) ??
+                managerFromClosestDeclaration(manifest.path, declaredManagers);
+    }
+    const primaryPackageJson = packageJsons[0];
+    const packageJson = primaryPackageJson
         ? {
-            name: rawPackageJson.name,
-            dependencies: rawPackageJson.dependencies ?? {},
-            devDependencies: rawPackageJson.devDependencies ?? {},
-            scripts: rawPackageJson.scripts ?? {},
-            moduleType: rawPackageJson.type === "module" ? "module" : "commonjs",
+            name: primaryPackageJson.name,
+            dependencies: Object.assign({}, ...packageJsons.map((p) => p.dependencies)),
+            devDependencies: Object.assign({}, ...packageJsons.map((p) => p.devDependencies)),
+            // Root scripts remain the default command surface. Repo facts reads packageJsons
+            // directly and adds executable --prefix commands for nested packages.
+            scripts: primaryPackageJson.scripts,
+            moduleType: primaryPackageJson.moduleType,
+            packageManager: primaryPackageJson.packageManager,
+            main: primaryPackageJson.main,
         }
         : undefined;
     const composerJsonPath = findFirst(files, "composer.json");
@@ -147,37 +238,45 @@ export function scanRepo(rootPath) {
     // Multi-module Maven/Gradle projects (parent + child modules) each have their own
     // pom.xml/build.gradle, and the module that actually declares the framework/Kotlin
     // plugin/test runner isn't necessarily the shallowest one. Aggregate all of them.
-    const pomPaths = findAllByNames(files, ["pom.xml"]);
-    const buildGradlePaths = findAllByNames(files, ["build.gradle", "build.gradle.kts"]);
-    const gemfilePath = findFirst(files, "Gemfile");
-    const goModPath = findFirst(files, "go.mod");
-    const cargoTomlPath = findFirst(files, "Cargo.toml");
+    const projectFiles = files.filter((file) => !isUnderNonProjectDir(file));
+    const pomPaths = findAllByNames(projectFiles, ["pom.xml"]);
+    const buildGradlePaths = findAllByNames(projectFiles, ["build.gradle", "build.gradle.kts"]);
+    const gemfilePath = findFirst(projectFiles, "Gemfile");
+    const goModPath = findFirst(projectFiles, "go.mod");
+    const cargoTomlPath = findFirst(projectFiles, "Cargo.toml");
     // .NET solutions routinely split into several .csproj files (domain/infra/web/tests);
     // picking just the "shallowest" one is close to arbitrary and often lands on a plain
     // class library that has neither the web framework nor the test runner reference.
     // Concatenate all of them so detection can find those references wherever they live.
-    const csprojPaths = findAllByExtension(files, ".csproj");
-    const packageSwiftPath = findFirst(files, "Package.swift");
+    const csprojPaths = findAllByExtension(projectFiles, ".csproj");
+    const packageSwiftPath = findFirst(projectFiles, "Package.swift");
     // Melos/pub workspaces have a root pubspec.yaml that's just workspace glue (no
     // `flutter`/`flutter_test` dependency) plus one real pubspec.yaml per package under
     // packages/*. Aggregate all of them so the actual framework/test runner is found.
-    const pubspecYamlPaths = findAllByNames(files, ["pubspec.yaml"]);
-    const cmakeListsPath = findFirst(files, "CMakeLists.txt");
+    const pubspecYamlPaths = findAllByNames(projectFiles, ["pubspec.yaml"]);
+    const cmakeListsPath = findFirst(projectFiles, "CMakeLists.txt");
     // Un Makefile que solo existe bajo docs/, tools/, etc. es tooling auxiliar (p. ej. el
     // Makefile de Sphinx en docs/ de Flask): sus targets no se pueden ejecutar desde la
     // raíz y no describen el proyecto. Mismo criterio que los manifiestos Python.
     const makefilePath = findFirstPreferringRealProjectDirs(files, "Makefile") ??
         findFirstPreferringRealProjectDirs(files, "makefile");
-    const mixExsPath = findFirst(files, "mix.exs");
-    const buildSbtPath = findFirst(files, "build.sbt");
-    const rDescriptionPath = findFirst(files, "DESCRIPTION");
-    const renvLockPath = findFirst(files, "renv.lock");
-    const toxIniPath = findFirst(files, "tox.ini");
+    const mixExsPath = findFirst(projectFiles, "mix.exs");
+    const buildSbtPath = findFirst(projectFiles, "build.sbt");
+    const rDescriptionPath = findFirst(projectFiles, "DESCRIPTION");
+    const renvLockPath = findFirst(projectFiles, "renv.lock");
+    const toxIniPath = findFirst(projectFiles, "tox.ini");
     const workflowPaths = files.filter((f) => {
         const normalized = f.split(path.sep).join("/");
         return (normalized.startsWith(".github/workflows/") &&
             (normalized.endsWith(".yml") || normalized.endsWith(".yaml")));
     });
+    const guidanceNames = new Set([
+        "CONTRIBUTING.md", ".editorconfig", "tsconfig.json", "pyproject.toml",
+    ]);
+    const guidancePaths = files.filter((file) => {
+        const normalized = file.split(path.sep).join("/");
+        return guidanceNames.has(path.posix.basename(normalized));
+    });
     return {
         rootPath,
         files,
@@ -185,6 +284,7 @@ export function scanRepo(rootPath) {
         hasDir: (relativeDir) => fs.existsSync(path.join(rootPath, relativeDir)) &&
             fs.statSync(path.join(rootPath, relativeDir)).isDirectory(),
         packageJson,
+        packageJsons,
         pyprojectToml: pyprojectPath ? readTextIfExists(path.join(rootPath, pyprojectPath)) : undefined,
         requirementsTxt: requirementsPath
             ? readTextIfExists(path.join(rootPath, requirementsPath))
@@ -214,5 +314,8 @@ export function scanRepo(rootPath) {
             content: readTextIfExists(path.join(rootPath, p)),
         }))
             .filter((w) => w.content !== undefined),
+        guidanceFiles: guidancePaths
+            .map((p) => ({ path: p.split(path.sep).join("/"), content: readTextIfExists(path.join(rootPath, p)) }))
+            .filter((f) => f.content !== undefined),
     };
 }