project-tiny-context-harness 0.2.60 → 0.2.61

package/dist/lib/source-pack-records.js

@@ -0,0 +1,161 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { listFiles, pathExists, readText } from "./fs.js";
+import { shouldExcludeRelativePath, shouldIncludeCodeFile, toPosix } from "./source-files.js";
+import { classifyCodeFile } from "./source-pack-classify.js";
+import { matchesAny } from "./source-pack-config.js";
+const execFileAsync = promisify(execFile);
+const GIT_LS_MAX_BUFFER = 64 * 1024 * 1024;
+const SENSITIVE_ASSIGNMENT_PATTERN = /^(\s*(?:[-*]\s*)?(?:[`"']?[\w.-]*(?:secret|token|cookie|password|api[_-]?key|credential|bearer|authorization)[\w.-]*[`"']?\s*[:=]\s*))(.+?)\s*$/i;
+export async function collectCodeRecords(projectRoot, warnings, options = {}) {
+    const gitCandidates = await listGitCandidateFiles(projectRoot);
+    const candidates = gitCandidates ?? (await listCandidateFiles(projectRoot));
+    const records = [];
+    for (const file of candidates) {
+        const relative = repoRelative(projectRoot, file);
+        if (!shouldIncludeCodeFile(relative) || matchesAny(relative, options.exclude ?? [])) {
+            continue;
+        }
+        if (options.include && options.include.length > 0 && !matchesAny(relative, options.include)) {
+            continue;
+        }
+        if (!(await isRegularFile(file))) {
+            continue;
+        }
+        const rawContent = await readText(file);
+        const redacted = redactSensitiveAssignments(rawContent);
+        if (redacted.count > 0) {
+            warnings.push(`${relative}: redacted ${redacted.count} sensitive assignment line(s)`);
+        }
+        const content = redacted.content;
+        const classification = classifyCodeFile(relative, content, options.areas ?? []);
+        records.push({
+            relative,
+            language: classification.language,
+            lines: countLines(content),
+            characters: content.length,
+            sha256: sha256(content),
+            summary: classification.summary,
+            content,
+            tags: classification.tags,
+            routes: classification.routes,
+            score: classification.score,
+            bucket: classification.bucket,
+            bundle: "omitted"
+        });
+    }
+    return records.sort((left, right) => left.relative.localeCompare(right.relative));
+}
+export async function collectContextArtifacts(projectRoot, warnings, includePatterns) {
+    const files = new Set();
+    for (const relative of ["AGENTS.md", "README.md", "DESIGN.md", "project_context/global.md", "project_context/architecture.md", "project_context/context.toml"]) {
+        await addIfExists(projectRoot, files, warnings, relative, relative.startsWith("project_context/"));
+    }
+    for (const file of await listFiles(path.join(projectRoot, "project_context"))) {
+        const relative = repoRelative(projectRoot, file);
+        if ((relative.endsWith(".md") || relative.endsWith(".toml")) && !shouldExcludeRelativePath(relative)) {
+            files.add(file);
+        }
+    }
+    const artifacts = [];
+    for (const file of [...files].sort((a, b) => repoRelative(projectRoot, a).localeCompare(repoRelative(projectRoot, b)))) {
+        const relative = repoRelative(projectRoot, file);
+        if (includePatterns && includePatterns.length > 0 && !matchesAny(relative, includePatterns)) {
+            continue;
+        }
+        const rawContent = await readText(file);
+        const redacted = redactSensitiveAssignments(rawContent);
+        if (redacted.count > 0) {
+            warnings.push(`${relative}: redacted ${redacted.count} sensitive assignment line(s)`);
+        }
+        artifacts.push({
+            relative,
+            content: redacted.content,
+            lines: countLines(redacted.content),
+            characters: redacted.content.length
+        });
+    }
+    return artifacts;
+}
+export function countRedactionWarnings(warnings) {
+    return warnings.filter((warning) => /redacted \d+ sensitive assignment line/i.test(warning)).length;
+}
+export function countLines(content) {
+    return content.length === 0 ? 0 : content.split(/\r\n|\r|\n/).length;
+}
+export function sha256(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+export function repoRelative(root, file) {
+    return toPosix(path.relative(root, file));
+}
+async function addIfExists(projectRoot, files, warnings, relative, required) {
+    const target = path.join(projectRoot, ...relative.split("/"));
+    if (await pathExists(target)) {
+        files.add(target);
+    }
+    else if (required) {
+        warnings.push(`${relative}: missing expected source file`);
+    }
+}
+async function listGitCandidateFiles(projectRoot) {
+    try {
+        const result = await execFileAsync("git", ["-C", projectRoot, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
+            encoding: "utf8",
+            maxBuffer: GIT_LS_MAX_BUFFER
+        });
+        return result.stdout.split("\0").filter(Boolean).map((relative) => path.join(projectRoot, ...toPosix(relative).split("/")));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function listCandidateFiles(projectRoot) {
+    const files = [];
+    await walkCandidates(projectRoot, projectRoot, files);
+    return files;
+}
+async function walkCandidates(projectRoot, current, files) {
+    let entries;
+    try {
+        entries = await fs.readdir(current, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const fullPath = path.join(current, entry.name);
+        const relative = repoRelative(projectRoot, fullPath);
+        if (entry.isDirectory()) {
+            if (!shouldExcludeRelativePath(relative)) {
+                await walkCandidates(projectRoot, fullPath, files);
+            }
+        }
+        else if (entry.isFile() && !shouldExcludeRelativePath(relative)) {
+            files.push(fullPath);
+        }
+    }
+}
+async function isRegularFile(target) {
+    try {
+        return (await fs.stat(target)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function redactSensitiveAssignments(content) {
+    let count = 0;
+    const lines = content.split(/\r?\n/).map((line) => {
+        const match = SENSITIVE_ASSIGNMENT_PATTERN.exec(line);
+        if (!match) {
+            return line;
+        }
+        count += 1;
+        return `${match[1]}[REDACTED]`;
+    });
+    return { content: lines.join("\n"), count };
+}

package/dist/lib/source-pack-render.d.ts

@@ -0,0 +1,12 @@
+import type { ContextAreaMapping, ContextArtifact, SourcePackOmitted, SourcePackRecord } from "./source-pack-types.js";
+export declare const SOURCE_PACK_EXPORT_HEADER = "Export artifact. Do not reference from project_context/context.toml.";
+export interface RenderMeta {
+    generatedAt: string;
+    outputPath: string;
+    command: string;
+    toolVersion: string;
+}
+export declare function renderFullProjectContextArtifact(contexts: ContextArtifact[], warnings: string[], meta: RenderMeta): string;
+export declare function renderCodeIndexArtifact(records: SourcePackRecord[], areas: ContextAreaMapping[], warnings: string[], meta: RenderMeta): string;
+export declare function renderBundleArtifact(title: string, records: SourcePackRecord[], contexts: ContextArtifact[], omitted: SourcePackOmitted, warnings: string[], meta: RenderMeta, policy: string): string;
+export declare function renderTaskContextArtifact(taskName: string, contexts: ContextArtifact[], records: SourcePackRecord[], verification: string[], omitted: SourcePackOmitted, warnings: string[], meta: RenderMeta): string;

package/dist/lib/source-pack-render.js

@@ -0,0 +1,235 @@
+export const SOURCE_PACK_EXPORT_HEADER = "Export artifact. Do not reference from project_context/context.toml.";
+export function renderFullProjectContextArtifact(contexts, warnings, meta) {
+    return [
+        "# Full Project Context Export",
+        "",
+        `> ${SOURCE_PACK_EXPORT_HEADER}`,
+        "",
+        "## Export Metadata",
+        "",
+        `- generated_at: ${meta.generatedAt}`,
+        `- output_path: ${meta.outputPath}`,
+        `- command: ${meta.command}`,
+        `- source_context_count: ${contexts.filter((context) => context.relative.startsWith("project_context/")).length}`,
+        "- warnings:",
+        ...renderWarningList(warnings),
+        "",
+        "## Export Boundary",
+        "",
+        "- This temporary artifact is for external planning and handoff only.",
+        "- Do not register it in project_context/context.toml.",
+        "",
+        "## Context Sources",
+        "",
+        ...contexts.map(renderContextArtifact),
+        ""
+    ].join("\n");
+}
+export function renderCodeIndexArtifact(records, areas, warnings, meta) {
+    const totalLines = records.reduce((sum, record) => sum + record.lines, 0);
+    const totalCharacters = records.reduce((sum, record) => sum + record.characters, 0);
+    return [
+        "# Code Index Export",
+        "",
+        `> ${SOURCE_PACK_EXPORT_HEADER}`,
+        "",
+        "## Export Metadata",
+        "",
+        `- generated_at: ${meta.generatedAt}`,
+        `- output_path: ${meta.outputPath}`,
+        `- command: ${meta.command}`,
+        `- tool_version: ${meta.toolVersion}`,
+        `- source_file_count: ${records.length}`,
+        `- total_lines: ${totalLines}`,
+        `- total_characters: ${totalCharacters}`,
+        "- warnings:",
+        ...renderWarningList(warnings),
+        "",
+        "## Repository Shape",
+        "",
+        renderRepositoryShape(records),
+        "",
+        "## Context Area Mapping",
+        "",
+        "Inferred buckets below are export routing only; they are not durable architecture or product ownership facts.",
+        areas.length > 0 ? areas.map((area) => `- ${area.id}: root=${area.root}; context=${area.context}`).join("\n") : "- No Context area mappings found.",
+        "",
+        "## Key Entry Points",
+        "",
+        renderRecordList(records.filter((record) => record.tags.includes("entry")).slice(0, 30)),
+        "",
+        "## API / Route Index",
+        "",
+        renderRecordList(records.filter((record) => record.tags.includes("api")).slice(0, 30), true),
+        "",
+        "## UI Surface Index",
+        "",
+        renderRecordList(records.filter((record) => record.tags.includes("ui")).slice(0, 30)),
+        "",
+        "## CLI / Worker / Script Index",
+        "",
+        renderRecordList(records.filter((record) => record.tags.includes("cli") || record.tags.includes("worker")).slice(0, 30)),
+        "",
+        "## Test / Verification Index",
+        "",
+        renderRecordList(records.filter((record) => record.tags.includes("test")).slice(0, 30)),
+        "",
+        "## Oversized Files",
+        "",
+        renderRecordList(records.filter((record) => record.tags.includes("oversized")).slice(0, 30)),
+        "",
+        "## Source File Index",
+        "",
+        renderSourceFileIndex(records),
+        ""
+    ].join("\n");
+}
+export function renderBundleArtifact(title, records, contexts, omitted, warnings, meta, policy) {
+    return [
+        `# ${title}`,
+        "",
+        `> ${SOURCE_PACK_EXPORT_HEADER}`,
+        "",
+        "## Export Metadata",
+        "",
+        `- generated_at: ${meta.generatedAt}`,
+        `- output_path: ${meta.outputPath}`,
+        `- command: ${meta.command}`,
+        `- source_file_count: ${records.length}`,
+        "- warnings:",
+        ...renderWarningList(warnings),
+        "",
+        "## Bundle Selection Policy",
+        "",
+        policy,
+        "",
+        "## Bundle Index",
+        "",
+        renderSourceFileIndex(records),
+        "",
+        "## Related Context Paths",
+        "",
+        contexts.length > 0 ? contexts.map((context) => `- ${context.relative} (${context.lines} lines)`).join("\n") : "- No related Context files selected.",
+        "",
+        "## Source Files",
+        "",
+        records.map(renderSourceRecord).join("\n\n") || "- No source files selected for this bundle.",
+        "",
+        "## Omitted Files Summary",
+        "",
+        renderOmittedSummary(omitted),
+        ""
+    ].join("\n");
+}
+export function renderTaskContextArtifact(taskName, contexts, records, verification, omitted, warnings, meta) {
+    return [
+        `# Task Context: ${taskName}`,
+        "",
+        `> ${SOURCE_PACK_EXPORT_HEADER}`,
+        "",
+        "## Export Metadata",
+        "",
+        `- generated_at: ${meta.generatedAt}`,
+        `- output_path: ${meta.outputPath}`,
+        `- command: ${meta.command}`,
+        "- warnings:",
+        ...renderWarningList(warnings),
+        "",
+        "## Boundary",
+        "",
+        "- This task pack is a temporary export selector output, not a durable fact source.",
+        "- Profile verification commands are listed only; export does not execute them.",
+        "",
+        "## Selected Context",
+        "",
+        ...contexts.map(renderContextArtifact),
+        "",
+        "## Selected Source Index",
+        "",
+        renderSourceFileIndex(records),
+        "",
+        "## Selected Source Files",
+        "",
+        records.map(renderSourceRecord).join("\n\n") || "- No selected source files matched the task filters.",
+        "",
+        "## Verification Entry Points",
+        "",
+        verification.length > 0 ? verification.map((entry) => `- ${entry}`).join("\n") : "- No profile verification entries selected.",
+        "",
+        "## Omitted / Support Notes",
+        "",
+        renderOmittedSummary(omitted),
+        ""
+    ].join("\n");
+}
+function renderContextArtifact(context) {
+    const fence = fenceFor(context.content);
+    return [`### ${context.relative}`, "", `${fence}markdown`, context.content.trimEnd(), fence, ""].join("\n");
+}
+function renderSourceRecord(record) {
+    const fence = fenceFor(record.content);
+    return [
+        `### ${record.relative}`,
+        "",
+        `Summary: ${record.summary}`,
+        "",
+        "Metadata:",
+        `- type: ${record.language}`,
+        `- lines: ${record.lines}`,
+        `- characters: ${record.characters}`,
+        `- sha256: ${record.sha256}`,
+        `- tags: ${record.tags.join(", ") || "none"}`,
+        `- routing_bucket: ${record.bucket} (export routing only)`,
+        "",
+        `${fence}${record.language}`,
+        record.content.trimEnd(),
+        fence
+    ].join("\n");
+}
+function renderSourceFileIndex(records) {
+    if (records.length === 0) {
+        return "- No source files matched.";
+    }
+    return [
+        "| Path | Type | Lines | Characters | SHA256 | Summary | Bundle | Tags |",
+        "|---|---:|---:|---:|---|---|---|---|",
+        ...records.map((record) => `| ${escapeTableCell(record.relative)} | ${escapeTableCell(record.language)} | ${record.lines} | ${record.characters} | ${record.sha256.slice(0, 12)} | ${escapeTableCell(record.summary)} | ${record.bundle} | ${escapeTableCell(record.tags.join(", "))} |`)
+    ].join("\n");
+}
+function renderRepositoryShape(records) {
+    const counts = new Map();
+    for (const record of records) {
+        const top = record.relative.split("/")[0] || ".";
+        counts.set(top, (counts.get(top) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+        .map(([name, count]) => `- ${name}: ${count} source file(s)`)
+        .join("\n") || "- No source files matched.";
+}
+function renderRecordList(records, includeRoutes = false) {
+    if (records.length === 0) {
+        return "- None detected.";
+    }
+    return records
+        .map((record) => `- ${record.relative}: ${record.summary}${includeRoutes && record.routes.length > 0 ? ` Routes: ${record.routes.join(", ")}` : ""}`)
+        .join("\n");
+}
+function renderWarningList(warnings) {
+    return warnings.length > 0 ? warnings.map((warning) => `  - ${warning}`) : ["  - none"];
+}
+function renderOmittedSummary(omitted) {
+    const reasons = Object.entries(omitted.reason_counts)
+        .sort((left, right) => left[0].localeCompare(right[0]))
+        .map(([reason, count]) => `  - ${reason}: ${count}`);
+    return [`- omitted_source_file_count: ${omitted.source_file_count}`, "- reason_counts:", ...(reasons.length > 0 ? reasons : ["  - none: 0"])].join("\n");
+}
+function fenceFor(content) {
+    let fence = "```";
+    while (content.includes(fence))
+        fence += "`";
+    return fence;
+}
+function escapeTableCell(value) {
+    return value.replace(/\r?\n/g, " ").replace(/\|/g, "\\|");
+}

package/dist/lib/source-pack-types.d.ts

@@ -0,0 +1,77 @@
+export type SourcePackMode = "code-index" | "source-pack" | "code-bundles" | "task-context";
+export interface SourcePackOptions {
+    mode: SourcePackMode;
+    check?: boolean;
+    now?: Date;
+    command?: string;
+    profile?: string;
+    includeContext?: string[];
+    includeCode?: string[];
+    bundleStrategy?: "auto" | "area" | "topdir" | "config";
+    maxPackFiles?: number;
+    maxBundleCharacters?: number;
+    redactionStrict?: boolean;
+    prune?: number;
+    taskName?: string;
+}
+export interface SourcePackArtifactReport {
+    kind: string;
+    name: string;
+    path: string;
+    sha256: string;
+    characters: number;
+    source_count: number;
+    source_line_count: number;
+    warning_count: number;
+}
+export interface SourcePackReport {
+    mode: SourcePackMode;
+    outputDirectory: string;
+    outputRelativePath: string;
+    artifacts: SourcePackArtifactReport[];
+    sourceFiles: string[];
+    sourceCodeCount: number;
+    totalLines: number;
+    totalCharacters: number;
+    redactionCount: number;
+    warnings: string[];
+    omitted: SourcePackOmitted;
+    recommendedUploadSets: Record<string, string[]>;
+    wrote: boolean;
+}
+export interface SourcePackOmitted {
+    source_file_count: number;
+    reason_counts: Record<string, number>;
+}
+export interface SourcePackRecord {
+    relative: string;
+    language: string;
+    lines: number;
+    characters: number;
+    sha256: string;
+    summary: string;
+    content: string;
+    tags: string[];
+    routes: string[];
+    score: number;
+    bucket: string;
+    bundle: "core" | "extended" | "task" | "task-support" | "omitted";
+}
+export interface SourcePackProfile {
+    context: string[];
+    code: string[];
+    exclude: string[];
+    verification: string[];
+    maxBundleCharacters?: number;
+}
+export interface ContextArtifact {
+    relative: string;
+    content: string;
+    lines: number;
+    characters: number;
+}
+export interface ContextAreaMapping {
+    id: string;
+    root: string;
+    context: string;
+}

package/dist/lib/source-pack-types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-tiny-context-harness",
-  "version": "0.2.60",
+  "version": "0.2.61",
   "description": "Minimal project memory and validation harness for AI coding agents.",
   "license": "MIT",
   "author": "Seven128",