project-tiny-context-harness 0.2.85 → 0.6.0

package/dist/lib/modularity.js

@@ -8,28 +8,40 @@ 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 MODULARITY_POLICIES = new Set([
+    DEFAULT_MODULARITY_POLICY,
+    "strict_except_generated",
+]);
+const COMPLEXITY_LIMITS = {
+    functionStatements: 80,
+    branchComplexity: 25,
+    exports: 24,
+    stateTransitions: 24,
+    responsibilities: 6,
+};
 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
+    /^\s*(?:\/\/|#|--|;)\s*generated by\b/im,
 ];
 const WAIVER_CATEGORIES = new Set([
     "generated",
     "third_party_reference",
     "legacy_migration",
     "aggregate_styles",
-    "fixture_snapshot"
+    "fixture_snapshot",
 ]);
 export async function runModularityCheck(projectRoot, options) {
     const config = await readConfig(projectRoot);
-    const { limit: configuredLimit, waiverValues, errors: configErrors } = validateModularityConfig(config.modularity);
+    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 waiverTargetErrors = await validateWaiverTargets(projectRoot, waivers, limit);
     const candidates = new Set();
+    const baselineRef = options.base ?? (options.touched ? "HEAD" : undefined);
     for (const file of options.files ?? []) {
         candidates.add(normalizeExplicitPath(projectRoot, file));
     }
@@ -49,20 +61,149 @@ export async function runModularityCheck(projectRoot, options) {
             continue;
         }
         const absolutePath = path.join(projectRoot, ...relativePath.split("/"));
-        if (!(await isRegularFile(absolutePath)) || (await isLikelyGeneratedFile(absolutePath))) {
+        if (!(await isRegularFile(absolutePath)) ||
+            (await isLikelyGeneratedFile(absolutePath))) {
             continue;
         }
-        const lines = countPhysicalLines(await fs.readFile(absolutePath, "utf8"));
+        const content = await fs.readFile(absolutePath, "utf8");
+        const lines = countPhysicalLines(content);
+        const metrics = analyzeModularity(content, relativePath);
+        const risks = modularityRisks(lines, limit, metrics);
+        const baselineContent = baselineRef
+            ? await gitFileAtRef(projectRoot, baselineRef, relativePath)
+            : undefined;
+        const baseline = baselineContent
+            ? analyzeFile(baselineContent, limit, relativePath)
+            : undefined;
+        const regressions = modularityRegressions({ lines, metrics, risks }, baseline);
         const waiver = waivers.get(relativePath);
-        files.push({ relativePath, lines, overLimit: lines > limit, waived: waiver });
+        files.push({
+            relativePath,
+            lines,
+            metrics,
+            risks,
+            regressions,
+            overLimit: risks.length > 0,
+            regressed: regressions.length > 0,
+            baseline,
+            waived: waiver,
+        });
     }
     const warnings = files
-        .filter((file) => file.overLimit && !file.waived)
-        .map((file) => `${file.relativePath}: ${file.lines} physical lines exceeds limit ${limit}`);
+        .filter((file) => file.regressed && !file.waived)
+        .map((file) => `${file.relativePath}: ${file.regressions.join("; ")}`);
     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] };
+        .filter((file) => file.regressed && file.waived)
+        .map((file) => `${file.relativePath}: ${file.regressions.join("; ")} but is waived by ${file.waived?.owner} until ${file.waived?.expiryCondition}`);
+    return {
+        limit,
+        files,
+        warnings,
+        waivedWarnings,
+        errors: [...configErrors, ...waiverErrors, ...waiverTargetErrors],
+    };
+}
+function analyzeFile(content, limit, relativePath) {
+    const lines = countPhysicalLines(content);
+    const metrics = analyzeModularity(content, relativePath);
+    return { lines, metrics, risks: modularityRisks(lines, limit, metrics) };
+}
+function modularityRegressions(current, baseline) {
+    if (!baseline) {
+        return current.risks;
+    }
+    const checks = [
+        {
+            current: current.metrics.maxFunctionStatements,
+            baseline: baseline.metrics.maxFunctionStatements,
+            limit: COMPLEXITY_LIMITS.functionStatements,
+            message: `${current.metrics.maxFunctionStatements} statements in one function exceeds limit ${COMPLEXITY_LIMITS.functionStatements}${formatMetricLocation(current.metrics.maxFunctionStatementsLocation)}`,
+        },
+        {
+            current: current.metrics.maxBranchComplexity,
+            baseline: baseline.metrics.maxBranchComplexity,
+            limit: COMPLEXITY_LIMITS.branchComplexity,
+            message: `${current.metrics.maxBranchComplexity} branch complexity exceeds limit ${COMPLEXITY_LIMITS.branchComplexity}${formatMetricLocation(current.metrics.maxBranchComplexityLocation)}`,
+        },
+        {
+            current: current.metrics.exports,
+            baseline: baseline.metrics.exports,
+            limit: COMPLEXITY_LIMITS.exports,
+            message: `${current.metrics.exports} exports exceeds limit ${COMPLEXITY_LIMITS.exports}`,
+        },
+        {
+            current: current.metrics.stateTransitions,
+            baseline: baseline.metrics.stateTransitions,
+            limit: COMPLEXITY_LIMITS.stateTransitions,
+            message: `${current.metrics.stateTransitions} state transitions exceeds limit ${COMPLEXITY_LIMITS.stateTransitions}`,
+        },
+        {
+            current: current.metrics.responsibilities.length,
+            baseline: baseline.metrics.responsibilities.length,
+            limit: COMPLEXITY_LIMITS.responsibilities,
+            message: `${current.metrics.responsibilities.length} module responsibilities exceeds limit ${COMPLEXITY_LIMITS.responsibilities}`,
+        },
+    ];
+    return checks
+        .filter((check) => check.current > check.limit && check.current > check.baseline)
+        .map((check) => check.message);
+}
+export function analyzeModularity(content, relativePath = "") {
+    const code = sanitizeCode(content);
+    const bodies = relativePath.toLowerCase().endsWith(".py")
+        ? pythonFunctionBodies(code)
+        : functionBodies(code);
+    const analyzedBodies = bodies.map((body) => ({
+        ...body,
+        statements: statementCount(body.body),
+        branches: branchComplexity(body.body),
+    }));
+    const statementPeak = maxMetricBody(analyzedBodies, "statements");
+    const branchPeak = maxMetricBody(analyzedBodies, "branches");
+    return {
+        maxFunctionStatements: statementPeak?.statements ?? 0,
+        ...(statementPeak
+            ? {
+                maxFunctionStatementsLocation: {
+                    symbol: statementPeak.symbol,
+                    line: statementPeak.line,
+                },
+            }
+            : {}),
+        maxBranchComplexity: branchPeak?.branches ?? 0,
+        ...(branchPeak
+            ? {
+                maxBranchComplexityLocation: {
+                    symbol: branchPeak.symbol,
+                    line: branchPeak.line,
+                },
+            }
+            : {}),
+        exports: exportCount(code),
+        stateTransitions: stateTransitionCount(code),
+        responsibilities: inferResponsibilities(code),
+    };
+}
+function modularityRisks(lines, lineLimit, metrics) {
+    const risks = [];
+    if (lines > lineLimit)
+        risks.push(`${lines} physical lines exceeds limit ${lineLimit}`);
+    if (metrics.maxFunctionStatements > COMPLEXITY_LIMITS.functionStatements) {
+        risks.push(`${metrics.maxFunctionStatements} statements in one function exceeds limit ${COMPLEXITY_LIMITS.functionStatements}${formatMetricLocation(metrics.maxFunctionStatementsLocation)}`);
+    }
+    if (metrics.maxBranchComplexity > COMPLEXITY_LIMITS.branchComplexity) {
+        risks.push(`${metrics.maxBranchComplexity} branch complexity exceeds limit ${COMPLEXITY_LIMITS.branchComplexity}${formatMetricLocation(metrics.maxBranchComplexityLocation)}`);
+    }
+    if (metrics.exports > COMPLEXITY_LIMITS.exports) {
+        risks.push(`${metrics.exports} exports exceeds limit ${COMPLEXITY_LIMITS.exports}`);
+    }
+    if (metrics.stateTransitions > COMPLEXITY_LIMITS.stateTransitions) {
+        risks.push(`${metrics.stateTransitions} state transitions exceeds limit ${COMPLEXITY_LIMITS.stateTransitions}`);
+    }
+    if (metrics.responsibilities.length > COMPLEXITY_LIMITS.responsibilities) {
+        risks.push(`${metrics.responsibilities.length} module responsibilities exceeds limit ${COMPLEXITY_LIMITS.responsibilities}`);
+    }
+    return risks;
 }
 export function countPhysicalLines(content) {
     if (content.length === 0) {
@@ -74,12 +215,277 @@ export function countPhysicalLines(content) {
     }
     return lines.length;
 }
+function sanitizeCode(content) {
+    const cursor = {
+        state: "code",
+        result: "",
+        index: 0,
+        regexCharacterClass: false,
+    };
+    while (cursor.index < content.length) {
+        if (cursor.state === "code")
+            scanCode(content, cursor);
+        else if (cursor.state === "line-comment")
+            scanLineComment(content, cursor);
+        else if (cursor.state === "block-comment")
+            scanBlockComment(content, cursor);
+        else if (cursor.state === "regex")
+            scanRegex(content, cursor);
+        else
+            scanQuoted(content, cursor);
+        cursor.index += 1;
+    }
+    return cursor.result;
+}
+function scanCode(content, cursor) {
+    const char = content[cursor.index];
+    const next = content[cursor.index + 1];
+    if (char === "/" && (next === "/" || next === "*")) {
+        cursor.state = next === "/" ? "line-comment" : "block-comment";
+        cursor.result += "  ";
+        cursor.index += 1;
+        return;
+    }
+    if (char === "/" && startsRegexLiteral(cursor.result)) {
+        cursor.state = "regex";
+        cursor.regexCharacterClass = false;
+        cursor.result += " ";
+        return;
+    }
+    const quoteState = quoteStateFor(char);
+    if (quoteState) {
+        cursor.state = quoteState;
+        cursor.result += " ";
+        return;
+    }
+    cursor.result += char;
+}
+function scanLineComment(content, cursor) {
+    const char = content[cursor.index];
+    if (isLineBreak(char))
+        cursor.state = "code";
+    cursor.result += isLineBreak(char) ? char : " ";
+}
+function scanBlockComment(content, cursor) {
+    const char = content[cursor.index];
+    if (char === "*" && content[cursor.index + 1] === "/") {
+        cursor.state = "code";
+        cursor.result += "  ";
+        cursor.index += 1;
+        return;
+    }
+    cursor.result += isLineBreak(char) ? char : " ";
+}
+function scanRegex(content, cursor) {
+    const char = content[cursor.index];
+    if (char === "\\") {
+        cursor.result += "  ";
+        cursor.index += 1;
+        return;
+    }
+    if (char === "[")
+        cursor.regexCharacterClass = true;
+    if (char === "]")
+        cursor.regexCharacterClass = false;
+    if (char === "/" && !cursor.regexCharacterClass)
+        cursor.state = "code";
+    cursor.result += isLineBreak(char) ? char : " ";
+}
+function scanQuoted(content, cursor) {
+    const char = content[cursor.index];
+    if (char === "\\") {
+        cursor.result += "  ";
+        cursor.index += 1;
+        return;
+    }
+    if (char === delimiterFor(cursor.state))
+        cursor.state = "code";
+    cursor.result += isLineBreak(char) ? char : " ";
+}
+function quoteStateFor(char) {
+    if (char === "'")
+        return "single";
+    if (char === '"')
+        return "double";
+    if (char === "`")
+        return "template";
+    return undefined;
+}
+function delimiterFor(state) {
+    if (state === "single")
+        return "'";
+    if (state === "double")
+        return '"';
+    return "`";
+}
+function isLineBreak(char) {
+    return char === "\n" || char === "\r";
+}
+function startsRegexLiteral(result) {
+    const trimmed = result.trimEnd();
+    if (!trimmed)
+        return true;
+    const previous = trimmed.at(-1) ?? "";
+    if (/[=(:,!&|?;\[{]/u.test(previous))
+        return true;
+    return /\b(?:return|throw|case|delete|void|typeof|instanceof|in|of)$/u.test(trimmed);
+}
+function functionBodies(code) {
+    const starts = new Map();
+    const add = (openingBrace, symbol) => {
+        const existing = starts.get(openingBrace);
+        if (!existing || existing === "<anonymous>")
+            starts.set(openingBrace, symbol);
+    };
+    for (const match of code.matchAll(/\bfunction\s*([A-Za-z_$][\w$]*)?[^{};]*\{/g)) {
+        const openingBrace = (match.index ?? 0) + match[0].lastIndexOf("{");
+        add(openingBrace, match[1] || "<anonymous>");
+    }
+    for (const match of code.matchAll(/=>\s*\{/g)) {
+        const openingBrace = (match.index ?? 0) + match[0].lastIndexOf("{");
+        add(openingBrace, inferArrowSymbol(code, match.index ?? 0));
+    }
+    for (const match of code.matchAll(/\b(?:async\s+)?(?:get\s+|set\s+)?([A-Za-z_$][\w$]*)\s*\([^;{}]*\)\s*(?::\s*[^={]+)?\{/g)) {
+        const prefix = match[0].trimStart();
+        if (/^(?:if|for|while|switch|catch|with)\b/u.test(prefix))
+            continue;
+        const openingBrace = (match.index ?? 0) + match[0].lastIndexOf("{");
+        add(openingBrace, match[1] || "<anonymous>");
+    }
+    return [...starts.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([openingBrace, symbol]) => {
+        const body = balancedBody(code, openingBrace);
+        return body === undefined
+            ? undefined
+            : {
+                body,
+                symbol,
+                line: lineNumberAt(code, openingBrace),
+            };
+    })
+        .filter((body) => body !== undefined);
+}
+function pythonFunctionBodies(code) {
+    const lines = code.split(/\r\n|\n|\r/u);
+    const bodies = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = /^(\s*)(?:async\s+)?def\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/u.exec(lines[index]);
+        if (!match)
+            continue;
+        const indentation = indentationWidth(match[1]);
+        const body = [];
+        for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+            const line = lines[cursor];
+            if (!line.trim()) {
+                body.push(line);
+                continue;
+            }
+            const leading = /^\s*/u.exec(line)?.[0] ?? "";
+            if (indentationWidth(leading) <= indentation)
+                break;
+            body.push(line);
+        }
+        bodies.push({ body: body.join("\n"), symbol: match[2], line: index + 1 });
+    }
+    return bodies;
+}
+function inferArrowSymbol(code, arrowIndex) {
+    const prefix = code.slice(Math.max(0, arrowIndex - 240), arrowIndex);
+    const assignment = /(?:\b(?:const|let|var)\s+|\b)([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*$/u.exec(prefix);
+    if (assignment?.[1])
+        return assignment[1];
+    const property = /([A-Za-z_$][\w$]*)\s*:\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*$/u.exec(prefix);
+    return property?.[1] ?? "<anonymous>";
+}
+function lineNumberAt(code, index) {
+    return code.slice(0, index).split(/\r\n|\n|\r/u).length;
+}
+function maxMetricBody(bodies, metric) {
+    let selected;
+    for (const body of bodies) {
+        if (!selected || body[metric] > selected[metric])
+            selected = body;
+    }
+    return selected;
+}
+function formatMetricLocation(location) {
+    return location
+        ? ` in function ${location.symbol} at line ${location.line}`
+        : "";
+}
+function indentationWidth(value) {
+    return [...value].reduce((width, character) => width + (character === "\t" ? 4 : 1), 0);
+}
+function balancedBody(code, openingBrace) {
+    let depth = 0;
+    for (let index = openingBrace; index < code.length; index += 1) {
+        if (code[index] === "{")
+            depth += 1;
+        if (code[index] === "}")
+            depth -= 1;
+        if (depth === 0)
+            return code.slice(openingBrace + 1, index);
+    }
+    return undefined;
+}
+function statementCount(body) {
+    const semicolons = body.match(/;/g)?.length ?? 0;
+    const structural = body.match(/\b(?:if|for|while|switch|case|catch|return|throw|break|continue)\b/g)?.length ?? 0;
+    return semicolons + structural;
+}
+function branchComplexity(body) {
+    const branches = body.match(/\b(?:if|for|while|case|catch)\b|\?|&&|\|\||\?\?/g)?.length ?? 0;
+    return 1 + branches;
+}
+function exportCount(code) {
+    let count = code.match(/\bexport\s+(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var|interface|type|enum|namespace)\b/g)?.length ?? 0;
+    for (const match of code.matchAll(/\bexport\s*\{([^}]*)\}/g)) {
+        count += match[1].split(",").filter((item) => item.trim()).length;
+    }
+    return count;
+}
+function stateTransitionCount(code) {
+    return (code.match(/\.(?:status|state|phase|workflow_status|campaign_status)\s*=|\b(?:transition|setState|setStatus|advanceState|mutateCampaign)[A-Za-z0-9_$]*\s*\(/g)?.length ?? 0);
+}
+function inferResponsibilities(code) {
+    const patterns = [
+        [
+            "filesystem",
+            /\b(?:readFile|writeFile|mkdir|rm|rename|readdir|stat|realpath)\s*\(/,
+        ],
+        ["process-or-git", /\b(?:spawn|execFile|runGit|process\.)/],
+        ["network", /\b(?:fetch|http\.|https\.|WebSocket|net\.)/],
+        ["parsing", /\b(?:parse|decode|deserialize)[A-Za-z0-9_$]*\s*\(/],
+        ["validation", /\b(?:assert|validate|reject)[A-Za-z0-9_$]*\s*\(/],
+        [
+            "state-machine",
+            /\.(?:status|state|phase)\s*=|\btransition[A-Za-z0-9_$]*\s*\(/,
+        ],
+        ["rendering", /\b(?:render|stringify|format)[A-Za-z0-9_$]*\s*\(/],
+        [
+            "persistence",
+            /\b(?:atomic|transaction|journal|lease|checkpoint)[A-Za-z0-9_$]*\b/i,
+        ],
+        ["cli", /\b(?:process\.argv|console\.|parseArgs|helpText)\b/],
+    ];
+    return patterns
+        .filter(([, pattern]) => pattern.test(code))
+        .map(([name]) => name);
+}
 async function gitTouchedFiles(projectRoot) {
     let result;
     try {
-        result = await execFileAsync("git", ["-C", projectRoot, "status", "--porcelain", "-z"], {
+        result = await execFileAsync("git", [
+            "-C",
+            projectRoot,
+            "status",
+            "--porcelain=v1",
+            "-z",
+            "--untracked-files=all",
+        ], {
             encoding: "utf8",
-            maxBuffer: GIT_MAX_BUFFER
+            maxBuffer: GIT_MAX_BUFFER,
         });
     }
     catch (error) {
@@ -106,10 +512,28 @@ async function gitTouchedFiles(projectRoot) {
 async function gitDiffFiles(projectRoot, base) {
     const result = await execFileAsync("git", ["-C", projectRoot, "diff", "--name-only", "-z", base, "--"], {
         encoding: "utf8",
-        maxBuffer: GIT_MAX_BUFFER
+        maxBuffer: GIT_MAX_BUFFER,
     });
     return result.stdout.split("\0").filter(Boolean);
 }
+async function gitFileAtRef(projectRoot, ref, relativePath) {
+    try {
+        const result = await execFileAsync("git", ["-C", projectRoot, "show", `${ref}:${relativePath}`], {
+            encoding: "utf8",
+            maxBuffer: GIT_MAX_BUFFER,
+        });
+        return result.stdout;
+    }
+    catch (error) {
+        const stderr = error && typeof error === "object" && "stderr" in error
+            ? String(error.stderr)
+            : "";
+        if (/does not exist in|exists on disk, but not in|path .* not in/i.test(stderr)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
 function isNotGitRepositoryError(error) {
     if (!error || typeof error !== "object") {
         return false;
@@ -118,9 +542,13 @@ function isNotGitRepositoryError(error) {
     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 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)) {
+    if (relative.startsWith("../") ||
+        relative === ".." ||
+        path.isAbsolute(relative)) {
         throw new Error(`check-modularity --file must stay inside the project root: ${value}`);
     }
     return normalizeGitPath(relative);
@@ -133,7 +561,9 @@ function validateModularityConfig(modularity) {
     if (modularity === undefined) {
         return { errors };
     }
-    if (!modularity || typeof modularity !== "object" || Array.isArray(modularity)) {
+    if (!modularity ||
+        typeof modularity !== "object" ||
+        Array.isArray(modularity)) {
         errors.push("<harnessRoot>/config.yaml modularity must be an object");
         return { errors };
     }
@@ -149,7 +579,8 @@ function validateModularityConfig(modularity) {
         }
     }
     if (value.policy !== undefined) {
-        if (typeof value.policy !== "string" || !MODULARITY_POLICIES.has(value.policy)) {
+        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 {
@@ -159,7 +590,11 @@ function validateModularityConfig(modularity) {
     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 };
+    return {
+        limit,
+        waiverValues: policy === "scoped_waivers" ? value.waivers : undefined,
+        errors,
+    };
 }
 function validateWaivers(projectRoot, waiverValues) {
     const waivers = new Map();
@@ -179,9 +614,23 @@ function validateWaivers(projectRoot, waiverValues) {
         }
         const relativePath = requiredWaiverString(waiver, "path", label, errors);
         const category = requiredWaiverString(waiver, "category", label, errors);
+        const owner = requiredWaiverString(waiver, "owner", label, errors);
+        const introducedAt = requiredWaiverString(waiver, "introduced_at", label, errors);
         const reason = requiredWaiverString(waiver, "reason", label, errors);
-        const futureSplitBoundary = requiredWaiverString(waiver, "future_split_boundary", label, errors);
-        if (!relativePath || !category || !reason || !futureSplitBoundary) {
+        const trackingIssue = requiredWaiverString(waiver, "tracking_issue", label, errors);
+        const expiryCondition = requiredWaiverString(waiver, "expiry_condition", label, errors);
+        if (!relativePath ||
+            !category ||
+            !owner ||
+            !introducedAt ||
+            !reason ||
+            !trackingIssue ||
+            !expiryCondition) {
+            continue;
+        }
+        if (!/^\d{4}-\d{2}-\d{2}$/u.test(introducedAt) ||
+            Number.isNaN(Date.parse(`${introducedAt}T00:00:00Z`))) {
+            errors.push(`${label}.introduced_at must be an ISO YYYY-MM-DD date`);
             continue;
         }
         if (!WAIVER_CATEGORIES.has(category)) {
@@ -204,12 +653,39 @@ function validateWaivers(projectRoot, waiverValues) {
         waivers.set(normalized, {
             relativePath: normalized,
             category,
+            owner,
+            introducedAt,
             reason,
-            futureSplitBoundary
+            trackingIssue,
+            expiryCondition,
         });
     }
     return { waivers, errors };
 }
+async function validateWaiverTargets(projectRoot, waivers, limit) {
+    const errors = [];
+    for (const waiver of waivers.values()) {
+        const label = `<harnessRoot>/config.yaml modularity waiver for ${waiver.relativePath}`;
+        if (!shouldIncludeCodeFile(waiver.relativePath)) {
+            errors.push(`${label} does not target a supported handwritten source file`);
+            continue;
+        }
+        const target = path.join(projectRoot, ...waiver.relativePath.split("/"));
+        if (!(await isRegularFile(target))) {
+            errors.push(`${label} references a missing source file`);
+            continue;
+        }
+        if (await isLikelyGeneratedFile(target)) {
+            errors.push(`${label} is unnecessary because generated files are excluded`);
+            continue;
+        }
+        const analyzed = analyzeFile(await fs.readFile(target, "utf8"), limit, waiver.relativePath);
+        if (analyzed.risks.length === 0) {
+            errors.push(`${label} is unnecessary because the source does not currently exceed a modularity threshold`);
+        }
+    }
+    return errors;
+}
 function requiredWaiverString(waiver, field, label, errors) {
     const value = waiver[field];
     if (typeof value !== "string" || value.trim().length === 0) {

package/dist/lib/package-json-config.js

@@ -12,19 +12,28 @@ export async function packageHarnessRoot(projectRoot) {
         return undefined;
     }
     const value = config.harnessFolderName;
-    return typeof value === "string" && value.trim() ? normalizeHarnessFolderName(value) : undefined;
+    return typeof value === "string" && value.trim()
+        ? normalizeHarnessFolderName(value)
+        : undefined;
 }
 export async function writePackageHarnessRoot(projectRoot, folderName) {
     const normalized = normalizeHarnessFolderName(folderName);
     const packagePath = path.join(projectRoot, "package.json");
-    const packageJson = (await pathExists(packagePath)) ? parsePackageJson(await readText(packagePath)) : {};
+    const packageJson = (await pathExists(packagePath))
+        ? parsePackageJson(await readText(packagePath))
+        : {};
     const existingConfig = packageJson.tyContext;
-    const nextConfig = existingConfig && typeof existingConfig === "object" && !Array.isArray(existingConfig)
-        ? { ...existingConfig, harnessFolderName: normalized }
+    const nextConfig = existingConfig &&
+        typeof existingConfig === "object" &&
+        !Array.isArray(existingConfig)
+        ? {
+            ...existingConfig,
+            harnessFolderName: normalized,
+        }
         : { harnessFolderName: normalized };
     const next = {
         ...packageJson,
-        tyContext: nextConfig
+        tyContext: nextConfig,
     };
     return writeTextIfChanged(packagePath, `${JSON.stringify(next, null, 2)}\n`);
 }

package/dist/lib/package-source.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged, } from "./fs.js";
 import { AGENTS_BLOCK_MARKERS } from "./managed-file.js";
 import { SOURCE_MAPPINGS_PATH } from "./paths.js";
 import { parseYaml } from "./yaml.js";
@@ -29,7 +29,9 @@ export async function checkSource(projectRoot) {
         for (const item of expected) {
             sourceHashes.set(item.relative, hash(item.content));
             const targetFile = path.join(target, item.relative);
-            const existing = (await pathExists(targetFile)) ? await readText(targetFile) : "";
+            const existing = (await pathExists(targetFile))
+                ? await readText(targetFile)
+                : "";
             if (hash(existing) !== hash(item.content)) {
                 drift.push(`${mapping.target}/${item.relative}`);
             }