project-tiny-context-harness 0.2.52 → 0.2.54

package/dist/lib/config.js

@@ -9,6 +9,10 @@ export function defaultConfig(root) {
             package: CANONICAL_CORE_PACKAGE,
             schema_version: CURRENT_SCHEMA_VERSION
         },
+        modularity: {
+            limit: 300,
+            policy: "strict_except_generated"
+        },
         managed_files: [
             { path: "AGENTS.md", strategy: "merge-block" },
             { path: "Makefile", strategy: "merge-block" },
@@ -46,6 +50,7 @@ export function normalizeConfig(value, root = ".agent") {
             package: value.core?.package ?? fallback.core.package,
             schema_version: value.core?.schema_version ?? fallback.core.schema_version
         },
+        modularity: value.modularity,
         managed_files: value.managed_files ?? fallback.managed_files,
         never_overwrite: value.never_overwrite ?? fallback.never_overwrite
     };

package/dist/lib/context-export.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { promisify } from "node:util";
 import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
 import { harnessRoot } from "./harness-root.js";
+import { SAFE_EXAMPLE_FILE_NAMES, shouldExcludeRelativePath, shouldIncludeCodeFile, toPosix } from "./source-files.js";
 const execFileAsync = promisify(execFile);
 const EXPORT_HEADER = "Export artifact. Do not reference from project_context/context.toml.";
 const DEFAULT_EXPORT_DIR = "tmp/sdlc/context-exports";
@@ -13,91 +14,6 @@ const MAX_TREE_ENTRIES = 300;
 const MAX_TREE_DEPTH = 4;
 const GIT_LS_MAX_BUFFER = 64 * 1024 * 1024;
 const APPROX_TEXT_TOKEN_LIMIT_CHARS = 8_000_000;
-const EXCLUDED_DIR_NAMES = new Set([
-    ".git",
-    ".artifacts",
-    ".cache",
-    ".next",
-    ".nuxt",
-    ".runtime",
-    ".turbo",
-    "artifacts",
-    "build",
-    "cache",
-    "captures",
-    "coverage",
-    "dist",
-    "logs",
-    "node_modules",
-    "out",
-    "playwright-report",
-    "raw-captures",
-    "reports",
-    "target",
-    "temp",
-    "test-reports",
-    "test-results",
-    "tmp"
-]);
-const SAFE_EXAMPLE_FILE_NAMES = new Set([".env.example", ".env.sample", ".env.template", "example.env", "sample.env"]);
-const EXCLUDED_FILE_PATTERNS = [
-    /^\.env(?:\.|$)/i,
-    /\.log$/i,
-    /\.min\.(?:css|js|mjs)$/i,
-    /(^|[-_.])(secret|secrets|cookie|cookies|credential|credentials|api-key|apikey|access-token|refresh-token|auth-token|private-key)([-_.]|$)/i,
-    /(^|[-_.])(raw-capture|capture-dump|licensed-payload|license-payload|test-report)([-_.]|$)/i,
-    /^(?:package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|poetry\.lock|pipfile\.lock|cargo\.lock)$/i,
-    /full-project-context-\d{8}T\d{6}Z\.md$/i,
-    /当前项目context-\d{8}T\d{6}Z\.md$/i,
-    /当前项目代码实现\.md$/i,
-    /(^|[-_.])(code-level-implementation|context-export|context-bundle)([-_.]|$)/i
-];
-const CODE_FILE_EXTENSIONS = [
-    ".bat",
-    ".cjs",
-    ".cmd",
-    ".go",
-    ".gql",
-    ".graphql",
-    ".js",
-    ".jsx",
-    ".jsonc",
-    ".mjs",
-    ".proto",
-    ".ps1",
-    ".py",
-    ".sh",
-    ".sql",
-    ".toml",
-    ".ts",
-    ".tsx",
-    ".vue",
-    ".yaml",
-    ".yml"
-];
-const CODE_FILE_BASE_NAMES = new Set([
-    ".env.example",
-    ".env.sample",
-    ".env.template",
-    "dockerfile",
-    "makefile",
-    "package.json",
-    "pyproject.toml",
-    "requirements.txt",
-    "setup.cfg",
-    "tsconfig.json"
-]);
-const CONFIG_JSON_NAMES = new Set([
-    "babel.config.json",
-    "biome.json",
-    "composer.json",
-    "deno.json",
-    "eslint.config.json",
-    "jsconfig.json",
-    "package.json",
-    "tsconfig.json",
-    "vite.config.json"
-]);
 const SENSITIVE_ASSIGNMENT_PATTERN = /^(\s*(?:[-*]\s*)?(?:[`"']?[\w.-]*(?:secret|token|cookie|password|api[_-]?key)[\w.-]*[`"']?\s*[:=]\s*))(.+?)\s*$/i;
 export async function runExportContext(projectRoot, options = {}) {
     const requestedModeCount = Number(options.full === true) + Number(options.code === true);
@@ -519,55 +435,6 @@ function buildImplementationGuide(records) {
         "- This file is a temporary implementation snapshot, not durable Context; durable project facts still belong in project_context/**."
     ].join("\n");
 }
-function shouldIncludeCodeFile(relative) {
-    if (shouldExcludeRelativePath(relative)) {
-        return false;
-    }
-    const normalized = toPosix(relative);
-    const lower = normalized.toLowerCase();
-    const base = path.posix.basename(lower);
-    if (CODE_FILE_BASE_NAMES.has(base) || base.startsWith("dockerfile.")) {
-        return true;
-    }
-    if (lower.endsWith(".dockerfile")) {
-        return true;
-    }
-    if (lower.endsWith(".json")) {
-        return isConfigJson(lower);
-    }
-    return CODE_FILE_EXTENSIONS.some((extension) => lower.endsWith(extension));
-}
-function shouldExcludeRelativePath(relative) {
-    const normalized = toPosix(relative);
-    const segments = normalized.split("/");
-    if (segments.some((segment) => EXCLUDED_DIR_NAMES.has(segment))) {
-        return true;
-    }
-    const base = segments[segments.length - 1] ?? "";
-    const lowerBase = base.toLowerCase();
-    return EXCLUDED_FILE_PATTERNS.some((pattern) => {
-        if (SAFE_EXAMPLE_FILE_NAMES.has(lowerBase) && pattern.source.startsWith("^\\.env")) {
-            return false;
-        }
-        return pattern.test(base) || pattern.test(normalized);
-    });
-}
-function isConfigJson(lowerRelative) {
-    const base = path.posix.basename(lowerRelative);
-    return (CONFIG_JSON_NAMES.has(base) ||
-        lowerRelative.endsWith(".schema.json") ||
-        lowerRelative.includes("/schema/") ||
-        lowerRelative.includes("/schemas/") ||
-        lowerRelative.includes("/config/") ||
-        lowerRelative.includes("/configs/") ||
-        lowerRelative.includes("/examples/") ||
-        lowerRelative.includes("/sample/") ||
-        lowerRelative.includes("/samples/") ||
-        base.includes("config") ||
-        base.includes("schema") ||
-        base.includes("example") ||
-        base.includes("sample"));
-}
 function summarizeCodeFile(relative, content, language) {
     const lower = relative.toLowerCase();
     const base = path.posix.basename(relative);
@@ -837,9 +704,6 @@ function timestampForFile(now) {
 function repoRelative(root, file) {
     return toPosix(path.relative(root, file));
 }
-function toPosix(value) {
-    return value.replace(/\\/g, "/");
-}
 function escapeTableCell(value) {
     return value.replace(/\r?\n/g, " ").replace(/\|/g, "\\|");
 }

package/dist/lib/migrations.d.ts

@@ -36,4 +36,4 @@ export declare function createUpgradePlan(projectRoot: string): Promise<UpgradeP
 export declare function hasUpgradePlanWork(plan: UpgradePlan): boolean;
 export declare function updateModeForPlan(plan: UpgradePlan): ReleaseUpdateMode;
 export declare function formatUpgradePlan(plan: UpgradePlan): string[];
-export declare function runMigrations(projectRoot: string): Promise<MigrationReport>;
+export declare function runMigrations(projectRoot: string, existingPlan?: UpgradePlan): Promise<MigrationReport>;

package/dist/lib/migrations.js

@@ -112,12 +112,15 @@ export function formatUpgradePlan(plan) {
     }
     return lines;
 }
-export async function runMigrations(projectRoot) {
+export async function runMigrations(projectRoot, existingPlan) {
     const report = { changed: [], skipped: [], manualRequired: [], blocked: [] };
     const root = await harnessRoot(projectRoot);
-    const plan = await createUpgradePlan(projectRoot);
+    const plan = existingPlan ?? (await createUpgradePlan(projectRoot));
     report.manualRequired.push(...plan.manual_required);
     report.blocked.push(...plan.blocked);
+    if (plan.blocked.length > 0) {
+        return report;
+    }
     for (const migration of migrations) {
         if (!migration.apply) {
             continue;
@@ -137,10 +140,14 @@ async function migrateBaseProjectContext(projectRoot, report) {
     await ensureDir(path.join(projectRoot, "project_context", "areas"));
     const files = [
         ["project_context/global.md", globalContextTemplate()],
-        ["project_context/architecture.md", architectureContextTemplate()],
-        ["project_context/areas/main.md", areaContextTemplate("main")],
-        ["project_context/areas/main/verification.md", verificationContextTemplate("main")]
+        ["project_context/architecture.md", architectureContextTemplate()]
     ];
+    if (await contextManifestReferences(projectRoot, "project_context/areas/main.md")) {
+        files.push(["project_context/areas/main.md", areaContextTemplate("main")]);
+    }
+    if (await contextManifestReferences(projectRoot, "project_context/areas/main/verification.md")) {
+        files.push(["project_context/areas/main/verification.md", verificationContextTemplate("main")]);
+    }
     for (const [relative, content] of files) {
         const target = path.join(projectRoot, ...relative.split("/"));
         if (await pathExists(target)) {
@@ -155,6 +162,13 @@ async function migrateBaseProjectContext(projectRoot, report) {
         }
     }
 }
+async function contextManifestReferences(projectRoot, relative) {
+    const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
+    if (!(await pathExists(manifestPath))) {
+        return true;
+    }
+    return manifestReferencesPath(await readText(manifestPath), relative);
+}
 async function detectGlobalContextSections(projectRoot, _root, migration) {
     const relative = "project_context/global.md";
     const target = path.join(projectRoot, ...relative.split("/"));
@@ -427,3 +441,7 @@ function ensureManifestDefaultArea(content) {
     lines.splice(nextTableIndex, 0, "default = true");
     return lines.join("\n");
 }
+function manifestReferencesPath(content, relative) {
+    const escaped = relative.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`^(?:\\s*)(?:context|path)\\s*=\\s*["']${escaped}["']\\s*$`, "im").test(content);
+}

package/dist/lib/modularity.d.ts

@@ -0,0 +1,27 @@
+export interface ModularityCheckOptions {
+    touched?: boolean;
+    base?: string;
+    files?: string[];
+    limit?: number;
+}
+export interface ModularityFileReport {
+    relativePath: string;
+    lines: number;
+    overLimit: boolean;
+    waived?: ModularityWaiver;
+}
+export interface ModularityCheckReport {
+    limit: number;
+    files: ModularityFileReport[];
+    warnings: string[];
+    waivedWarnings: string[];
+    errors: string[];
+}
+export interface ModularityWaiver {
+    relativePath: string;
+    category: string;
+    reason: string;
+    futureSplitBoundary: string;
+}
+export declare function runModularityCheck(projectRoot: string, options: ModularityCheckOptions): Promise<ModularityCheckReport>;
+export declare function countPhysicalLines(content: string): number;

package/dist/lib/modularity.js

@@ -0,0 +1,233 @@
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { readConfig } from "./config.js";
+import { shouldIncludeCodeFile, toPosix } from "./source-files.js";
+const execFileAsync = promisify(execFile);
+const GIT_MAX_BUFFER = 16 * 1024 * 1024;
+const DEFAULT_LINE_LIMIT = 300;
+const DEFAULT_MODULARITY_POLICY = "scoped_waivers";
+const MODULARITY_POLICIES = new Set([DEFAULT_MODULARITY_POLICY, "strict_except_generated"]);
+const GENERATED_FILE_PATTERNS = [
+    /^\s*(?:\/\/|#|--|;)\s*@generated\b/im,
+    /^\s*(?:\/\/|#|--|;)\s*code generated .*do not edit\.?\s*$/im,
+    /^\s*(?:\/\/|#|--|;)\s*do not edit\.?\s*$/im,
+    /^\s*(?:\/\/|#|--|;|<!--)\s*<auto-generated\b/im,
+    /^\s*(?:\/\/|#|--|;)\s*this file was generated\b/im,
+    /^\s*(?:\/\/|#|--|;)\s*generated by\b/im
+];
+const WAIVER_CATEGORIES = new Set([
+    "generated",
+    "third_party_reference",
+    "legacy_migration",
+    "aggregate_styles",
+    "fixture_snapshot"
+]);
+export async function runModularityCheck(projectRoot, options) {
+    const config = await readConfig(projectRoot);
+    const { limit: configuredLimit, waiverValues, errors: configErrors } = validateModularityConfig(config.modularity);
+    const { waivers, errors: waiverErrors } = validateWaivers(projectRoot, waiverValues);
+    const limit = options.limit ?? configuredLimit ?? DEFAULT_LINE_LIMIT;
+    const candidates = new Set();
+    for (const file of options.files ?? []) {
+        candidates.add(normalizeExplicitPath(projectRoot, file));
+    }
+    if (options.touched) {
+        for (const relative of await gitTouchedFiles(projectRoot)) {
+            candidates.add(normalizeGitPath(relative));
+        }
+    }
+    if (options.base) {
+        for (const relative of await gitDiffFiles(projectRoot, options.base)) {
+            candidates.add(normalizeGitPath(relative));
+        }
+    }
+    const files = [];
+    for (const relativePath of [...candidates].sort()) {
+        if (!shouldIncludeCodeFile(relativePath)) {
+            continue;
+        }
+        const absolutePath = path.join(projectRoot, ...relativePath.split("/"));
+        if (!(await isRegularFile(absolutePath)) || (await isLikelyGeneratedFile(absolutePath))) {
+            continue;
+        }
+        const lines = countPhysicalLines(await fs.readFile(absolutePath, "utf8"));
+        const waiver = waivers.get(relativePath);
+        files.push({ relativePath, lines, overLimit: lines > limit, waived: waiver });
+    }
+    const warnings = files
+        .filter((file) => file.overLimit && !file.waived)
+        .map((file) => `${file.relativePath}: ${file.lines} physical lines exceeds limit ${limit}`);
+    const waivedWarnings = files
+        .filter((file) => file.overLimit && file.waived)
+        .map((file) => `${file.relativePath}: ${file.lines} physical lines exceeds limit ${limit} but is waived as ${file.waived?.category}`);
+    return { limit, files, warnings, waivedWarnings, errors: [...configErrors, ...waiverErrors] };
+}
+export function countPhysicalLines(content) {
+    if (content.length === 0) {
+        return 0;
+    }
+    const lines = content.split(/\r\n|\n|\r/);
+    if (lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines.length;
+}
+async function gitTouchedFiles(projectRoot) {
+    let result;
+    try {
+        result = await execFileAsync("git", ["-C", projectRoot, "status", "--porcelain", "-z"], {
+            encoding: "utf8",
+            maxBuffer: GIT_MAX_BUFFER
+        });
+    }
+    catch (error) {
+        if (isNotGitRepositoryError(error)) {
+            return [];
+        }
+        throw error;
+    }
+    const records = result.stdout.split("\0").filter(Boolean);
+    const files = [];
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        const status = record.slice(0, 2);
+        const relative = record.slice(3);
+        if (relative) {
+            files.push(relative);
+        }
+        if (status.includes("R") || status.includes("C")) {
+            index += 1;
+        }
+    }
+    return files;
+}
+async function gitDiffFiles(projectRoot, base) {
+    const result = await execFileAsync("git", ["-C", projectRoot, "diff", "--name-only", "-z", base, "--"], {
+        encoding: "utf8",
+        maxBuffer: GIT_MAX_BUFFER
+    });
+    return result.stdout.split("\0").filter(Boolean);
+}
+function isNotGitRepositoryError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const stderr = "stderr" in error && typeof error.stderr === "string" ? error.stderr : "";
+    return /not a git repository/i.test(stderr);
+}
+function normalizeExplicitPath(projectRoot, value) {
+    const absolute = path.isAbsolute(value) ? path.resolve(value) : path.resolve(projectRoot, value);
+    const relative = toPosix(path.relative(projectRoot, absolute));
+    if (relative.startsWith("../") || relative === ".." || path.isAbsolute(relative)) {
+        throw new Error(`check-modularity --file must stay inside the project root: ${value}`);
+    }
+    return normalizeGitPath(relative);
+}
+function normalizeGitPath(value) {
+    return toPosix(value).replace(/^\.\//, "");
+}
+function validateModularityConfig(modularity) {
+    const errors = [];
+    if (modularity === undefined) {
+        return { errors };
+    }
+    if (!modularity || typeof modularity !== "object" || Array.isArray(modularity)) {
+        errors.push("<harnessRoot>/config.yaml modularity must be an object");
+        return { errors };
+    }
+    const value = modularity;
+    let limit;
+    let policy = DEFAULT_MODULARITY_POLICY;
+    if (value.limit !== undefined) {
+        if (!Number.isInteger(value.limit) || Number(value.limit) <= 0) {
+            errors.push("<harnessRoot>/config.yaml modularity.limit must be a positive integer");
+        }
+        else {
+            limit = Number(value.limit);
+        }
+    }
+    if (value.policy !== undefined) {
+        if (typeof value.policy !== "string" || !MODULARITY_POLICIES.has(value.policy)) {
+            errors.push("<harnessRoot>/config.yaml modularity.policy must be one of scoped_waivers, strict_except_generated");
+        }
+        else {
+            policy = value.policy;
+        }
+    }
+    if (policy === "strict_except_generated" && value.waivers !== undefined) {
+        errors.push("<harnessRoot>/config.yaml modularity.waivers is not allowed when modularity.policy is strict_except_generated");
+    }
+    return { limit, waiverValues: policy === "scoped_waivers" ? value.waivers : undefined, errors };
+}
+function validateWaivers(projectRoot, waiverValues) {
+    const waivers = new Map();
+    const errors = [];
+    if (waiverValues === undefined) {
+        return { waivers, errors };
+    }
+    if (!Array.isArray(waiverValues)) {
+        errors.push("<harnessRoot>/config.yaml modularity.waivers must be an array");
+        return { waivers, errors };
+    }
+    for (const [index, waiver] of waiverValues.entries()) {
+        const label = `<harnessRoot>/config.yaml modularity.waivers[${index}]`;
+        if (!waiver || typeof waiver !== "object") {
+            errors.push(`${label} must be an object`);
+            continue;
+        }
+        const relativePath = requiredWaiverString(waiver, "path", label, errors);
+        const category = requiredWaiverString(waiver, "category", label, errors);
+        const reason = requiredWaiverString(waiver, "reason", label, errors);
+        const futureSplitBoundary = requiredWaiverString(waiver, "future_split_boundary", label, errors);
+        if (!relativePath || !category || !reason || !futureSplitBoundary) {
+            continue;
+        }
+        if (!WAIVER_CATEGORIES.has(category)) {
+            errors.push(`${label}.category must be one of generated, third_party_reference, legacy_migration, aggregate_styles, fixture_snapshot`);
+            continue;
+        }
+        let normalized;
+        try {
+            normalized = normalizeExplicitPath(projectRoot, relativePath);
+        }
+        catch {
+            errors.push(`${label}.path must stay inside the project root: ${relativePath}`);
+            continue;
+        }
+        const existing = waivers.get(normalized);
+        if (existing) {
+            errors.push(`${label}.path duplicates an existing modularity waiver for ${normalized}`);
+            continue;
+        }
+        waivers.set(normalized, {
+            relativePath: normalized,
+            category,
+            reason,
+            futureSplitBoundary
+        });
+    }
+    return { waivers, errors };
+}
+function requiredWaiverString(waiver, field, label, errors) {
+    const value = waiver[field];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        errors.push(`${label}.${field} must be a non-empty string`);
+        return undefined;
+    }
+    return value.trim();
+}
+async function isRegularFile(target) {
+    try {
+        return (await fs.stat(target)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isLikelyGeneratedFile(target) {
+    const content = await fs.readFile(target, "utf8");
+    const sample = content.slice(0, 8192);
+    return GENERATED_FILE_PATTERNS.some((pattern) => pattern.test(sample));
+}

package/dist/lib/source-files.d.ts

@@ -0,0 +1,4 @@
+export declare const SAFE_EXAMPLE_FILE_NAMES: Set<string>;
+export declare function shouldIncludeCodeFile(relative: string): boolean;
+export declare function shouldExcludeRelativePath(relative: string): boolean;
+export declare function toPosix(value: string): string;

package/dist/lib/source-files.js

@@ -0,0 +1,138 @@
+import path from "node:path";
+const EXCLUDED_DIR_NAMES = new Set([
+    ".git",
+    ".artifacts",
+    ".cache",
+    ".next",
+    ".nuxt",
+    ".runtime",
+    ".turbo",
+    "artifacts",
+    "build",
+    "cache",
+    "captures",
+    "coverage",
+    "dist",
+    "logs",
+    "node_modules",
+    "out",
+    "playwright-report",
+    "raw-captures",
+    "reports",
+    "target",
+    "temp",
+    "test-reports",
+    "test-results",
+    "tmp"
+]);
+export const SAFE_EXAMPLE_FILE_NAMES = new Set([".env.example", ".env.sample", ".env.template", "example.env", "sample.env"]);
+const EXCLUDED_FILE_PATTERNS = [
+    /^\.env(?:\.|$)/i,
+    /\.log$/i,
+    /\.min\.(?:css|js|mjs)$/i,
+    /(^|[-_.])(secret|secrets|cookie|cookies|credential|credentials|api-key|apikey|access-token|refresh-token|auth-token|private-key)([-_.]|$)/i,
+    /(^|[-_.])(raw-capture|capture-dump|licensed-payload|license-payload|test-report)([-_.]|$)/i,
+    /^(?:package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|poetry\.lock|pipfile\.lock|cargo\.lock)$/i,
+    /full-project-context-\d{8}T\d{6}Z\.md$/i,
+    /当前项目context-\d{8}T\d{6}Z\.md$/i,
+    /当前项目代码实现\.md$/i,
+    /(^|[-_.])(code-level-implementation|context-export|context-bundle)([-_.]|$)/i
+];
+const CODE_FILE_EXTENSIONS = [
+    ".bat",
+    ".cjs",
+    ".cmd",
+    ".go",
+    ".gql",
+    ".graphql",
+    ".js",
+    ".jsx",
+    ".jsonc",
+    ".mjs",
+    ".proto",
+    ".ps1",
+    ".py",
+    ".sh",
+    ".sql",
+    ".toml",
+    ".ts",
+    ".tsx",
+    ".vue",
+    ".yaml",
+    ".yml"
+];
+const CODE_FILE_BASE_NAMES = new Set([
+    ".env.example",
+    ".env.sample",
+    ".env.template",
+    "dockerfile",
+    "makefile",
+    "package.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "setup.cfg",
+    "tsconfig.json"
+]);
+const CONFIG_JSON_NAMES = new Set([
+    "babel.config.json",
+    "biome.json",
+    "composer.json",
+    "deno.json",
+    "eslint.config.json",
+    "jsconfig.json",
+    "package.json",
+    "tsconfig.json",
+    "vite.config.json"
+]);
+export function shouldIncludeCodeFile(relative) {
+    if (shouldExcludeRelativePath(relative)) {
+        return false;
+    }
+    const normalized = toPosix(relative);
+    const lower = normalized.toLowerCase();
+    const base = path.posix.basename(lower);
+    if (CODE_FILE_BASE_NAMES.has(base) || base.startsWith("dockerfile.")) {
+        return true;
+    }
+    if (lower.endsWith(".dockerfile")) {
+        return true;
+    }
+    if (lower.endsWith(".json")) {
+        return isConfigJson(lower);
+    }
+    return CODE_FILE_EXTENSIONS.some((extension) => lower.endsWith(extension));
+}
+export function shouldExcludeRelativePath(relative) {
+    const normalized = toPosix(relative);
+    const segments = normalized.split("/");
+    if (segments.some((segment) => EXCLUDED_DIR_NAMES.has(segment))) {
+        return true;
+    }
+    const base = segments[segments.length - 1] ?? "";
+    const lowerBase = base.toLowerCase();
+    return EXCLUDED_FILE_PATTERNS.some((pattern) => {
+        if (SAFE_EXAMPLE_FILE_NAMES.has(lowerBase) && pattern.source.startsWith("^\\.env")) {
+            return false;
+        }
+        return pattern.test(base) || pattern.test(normalized);
+    });
+}
+export function toPosix(value) {
+    return value.replace(/\\/g, "/");
+}
+function isConfigJson(lowerRelative) {
+    const base = path.posix.basename(lowerRelative);
+    return (CONFIG_JSON_NAMES.has(base) ||
+        lowerRelative.endsWith(".schema.json") ||
+        lowerRelative.includes("/schema/") ||
+        lowerRelative.includes("/schemas/") ||
+        lowerRelative.includes("/config/") ||
+        lowerRelative.includes("/configs/") ||
+        lowerRelative.includes("/examples/") ||
+        lowerRelative.includes("/sample/") ||
+        lowerRelative.includes("/samples/") ||
+        base.includes("config") ||
+        base.includes("schema") ||
+        base.includes("example") ||
+        base.includes("sample"));
+}

package/dist/lib/types.d.ts

@@ -3,9 +3,21 @@ export interface HarnessConfig {
         package: string;
         schema_version: string;
     };
+    modularity?: HarnessModularityConfig;
     managed_files: ManagedFile[];
     never_overwrite: string[];
 }
+export interface HarnessModularityConfig {
+    limit?: number;
+    policy?: "scoped_waivers" | "strict_except_generated";
+    waivers?: ModularityWaiverConfig[];
+}
+export interface ModularityWaiverConfig {
+    path?: string;
+    category?: string;
+    reason?: string;
+    future_split_boundary?: string;
+}
 export interface ManagedFile {
     path: string;
     strategy: "merge-block" | "generated" | "generated-compat" | "managed" | "merge-with-local" | "create-if-missing";

package/dist/lib/upgrade.d.ts

@@ -1 +1,10 @@
+export interface UpgradeRunReport {
+    lines: string[];
+    blocked: boolean;
+}
+export declare class UpgradeBlockedError extends Error {
+    readonly lines: string[];
+    constructor(lines: string[]);
+}
 export declare function runUpgrade(projectRoot: string): Promise<string[]>;
+export declare function runUpgradeReport(projectRoot: string): Promise<UpgradeRunReport>;