@praneeth_54/agentdoctor 2.1.0 → 3.0.0

package/dist/product/org/model.js

@@ -0,0 +1,195 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { redactSecrets } from "../../platform/security/redact.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { pathExists, readJsonFile } from "../../utils/fs.js";
+const FORBIDDEN_KEY = /^(secret|token|password|api[_-]?key|credential|private[_-]?key)$/i;
+function modelPath(root) {
+    return path.join(resolveRepoRoot(root), ".agentdoctor", "org", "model.json");
+}
+function sanitizeString(value) {
+    return redactSecrets(value).text.slice(0, 2000);
+}
+function sanitizeEntityRef(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    for (const key of Object.keys(o)) {
+        if (FORBIDDEN_KEY.test(key))
+            return null;
+    }
+    const id = typeof o.id === "string" ? sanitizeString(o.id.trim()) : "";
+    const name = typeof o.name === "string" ? sanitizeString(o.name.trim()) : "";
+    if (!id || !name)
+        return null;
+    const description = typeof o.description === "string" ? sanitizeString(o.description.trim()) : undefined;
+    return {
+        id,
+        name,
+        ...(description !== undefined && description.length > 0 ? { description } : {}),
+    };
+}
+function sanitizeProject(raw, catalogRoot) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    for (const key of Object.keys(o)) {
+        if (FORBIDDEN_KEY.test(key))
+            return null;
+    }
+    const id = typeof o.id === "string" ? sanitizeString(o.id.trim()) : "";
+    const name = typeof o.name === "string" ? sanitizeString(o.name.trim()) : "";
+    const rootPathRaw = typeof o.rootPath === "string" ? o.rootPath.trim() : catalogRoot;
+    if (!id || !name)
+        return null;
+    const resolved = path.isAbsolute(rootPathRaw)
+        ? path.normalize(rootPathRaw)
+        : path.normalize(path.join(catalogRoot, rootPathRaw));
+    if (!resolved.startsWith(catalogRoot)) {
+        return null;
+    }
+    const teamIds = Array.isArray(o.teamIds)
+        ? o.teamIds.filter((x) => typeof x === "string").map((x) => sanitizeString(x))
+        : [];
+    const serviceIds = Array.isArray(o.serviceIds)
+        ? o.serviceIds.filter((x) => typeof x === "string").map((x) => sanitizeString(x))
+        : [];
+    const ownerIds = Array.isArray(o.ownerIds)
+        ? o.ownerIds.filter((x) => typeof x === "string").map((x) => sanitizeString(x))
+        : [];
+    return { id, name, rootPath: resolved, teamIds, serviceIds, ownerIds };
+}
+function emptyModel(catalogRoot) {
+    return {
+        schemaVersion: 1,
+        updatedAt: new Date().toISOString(),
+        catalogRoot,
+        teams: [],
+        projects: [],
+        services: [],
+        owners: [],
+        truth: "VERIFIED",
+        limitations: [
+            "Org model is repo-local metadata only — not synced across machines or tenants.",
+            "Secret-like fields are rejected on load/save; values are redacted when persisted.",
+            "Linking a project root does not grant cross-repo file access — workspace rules still apply.",
+        ],
+    };
+}
+export async function loadOrganizationModel(rootInput) {
+    const catalogRoot = resolveRepoRoot(rootInput);
+    const file = modelPath(catalogRoot);
+    if (!(await pathExists(file))) {
+        return emptyModel(catalogRoot);
+    }
+    const parsed = await readJsonFile(file, DEFAULT_MAX_FILE_SIZE_BYTES);
+    if (!parsed.ok || typeof parsed.data !== "object" || parsed.data === null) {
+        return {
+            ...emptyModel(catalogRoot),
+            truth: "PARTIAL",
+            limitations: [
+                ...emptyModel(catalogRoot).limitations,
+                "Corrupt org model file — using empty model.",
+            ],
+        };
+    }
+    const o = parsed.data;
+    const teams = [];
+    const services = [];
+    const owners = [];
+    const projects = [];
+    if (Array.isArray(o.teams)) {
+        for (const item of o.teams) {
+            const ref = sanitizeEntityRef(item);
+            if (ref)
+                teams.push(ref);
+        }
+    }
+    if (Array.isArray(o.services)) {
+        for (const item of o.services) {
+            const ref = sanitizeEntityRef(item);
+            if (ref)
+                services.push(ref);
+        }
+    }
+    if (Array.isArray(o.owners)) {
+        for (const item of o.owners) {
+            const ref = sanitizeEntityRef(item);
+            if (ref)
+                owners.push(ref);
+        }
+    }
+    if (Array.isArray(o.projects)) {
+        for (const item of o.projects) {
+            const link = sanitizeProject(item, catalogRoot);
+            if (link)
+                projects.push(link);
+        }
+    }
+    return {
+        schemaVersion: 1,
+        updatedAt: typeof o.updatedAt === "string" && o.updatedAt.trim()
+            ? o.updatedAt.trim()
+            : new Date().toISOString(),
+        catalogRoot,
+        teams,
+        projects,
+        services,
+        owners,
+        truth: "VERIFIED",
+        limitations: emptyModel(catalogRoot).limitations,
+    };
+}
+export async function saveOrganizationModel(rootInput, model) {
+    const catalogRoot = resolveRepoRoot(rootInput);
+    const teams = model.teams
+        .map((t) => sanitizeEntityRef(t))
+        .filter((t) => t !== null);
+    const services = model.services
+        .map((s) => sanitizeEntityRef(s))
+        .filter((s) => s !== null);
+    const owners = model.owners
+        .map((o) => sanitizeEntityRef(o))
+        .filter((o) => o !== null);
+    const projects = model.projects
+        .map((p) => sanitizeProject(p, catalogRoot))
+        .filter((p) => p !== null);
+    const record = {
+        ...emptyModel(catalogRoot),
+        teams,
+        services,
+        owners,
+        projects,
+        updatedAt: new Date().toISOString(),
+    };
+    const dir = path.dirname(modelPath(catalogRoot));
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(modelPath(catalogRoot), `${JSON.stringify(record, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    return record;
+}
+/** Register or update a project link under the catalog root (path must stay within catalogRoot). */
+export async function linkProjectToOrgModel(rootInput, link) {
+    const catalogRoot = resolveRepoRoot(rootInput);
+    const current = await loadOrganizationModel(catalogRoot);
+    const rootPath = link.rootPath ?? catalogRoot;
+    const sanitized = sanitizeProject({ ...link, rootPath }, catalogRoot);
+    if (!sanitized) {
+        throw new Error("Invalid project link — path escape or forbidden fields");
+    }
+    const projects = current.projects.filter((p) => p.id !== sanitized.id);
+    projects.push(sanitized);
+    return saveOrganizationModel(catalogRoot, {
+        teams: current.teams,
+        services: current.services,
+        owners: current.owners,
+        projects,
+    });
+}
+export function resolveLinkedProjectRoot(model, projectId) {
+    const hit = model.projects.find((p) => p.id === projectId);
+    return hit?.rootPath ?? null;
+}

package/dist/product/privacy/doctor.d.ts

@@ -0,0 +1,13 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface PrivacyFinding {
+    id: string;
+    label: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface PrivacyDoctorReport {
+    root: string;
+    findings: PrivacyFinding[];
+    limitations: string[];
+}
+export declare function analyzePrivacySurface(rootInput: string): Promise<PrivacyDoctorReport>;

package/dist/product/privacy/doctor.js

@@ -0,0 +1,90 @@
+import { loadLatestBrain, searchBrain } from "../../core/brain-cli/service.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { lineNumberAt, loadProjectSourceFiles } from "../evidence-scan.js";
+const PII_PATTERNS = [
+    {
+        id: "email-like",
+        label: "Email-like string",
+        re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+    },
+    {
+        id: "ssn-like",
+        label: "SSN-like digit groups",
+        re: /\b\d{3}-\d{2}-\d{4}\b/g,
+    },
+    {
+        id: "credit-card-like",
+        label: "Credit-card-like digit groups",
+        re: /\b(?:\d[ -]*?){13,19}\b/g,
+    },
+];
+function redactPiiExcerpt(line, match) {
+    const idx = line.indexOf(match);
+    if (idx < 0)
+        return "[REDACTED]";
+    const before = line.slice(0, idx).slice(-24);
+    const after = line.slice(idx + match.length).slice(0, 12);
+    return `${before}[REDACTED]${after}`.trim().slice(0, 120);
+}
+export async function analyzePrivacySurface(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const limitations = [
+        "Privacy doctor is a lightweight PII-ish heuristic scan — not legal/compliance advice (not GDPR/HIPAA/PCI attestation).",
+        "Matches are INFERRED; many are fixtures, tests, or placeholders.",
+        "Matched values are redacted in excerpts; never export raw PII from this report.",
+    ];
+    const findings = [];
+    const { files } = await loadProjectSourceFiles(root, () => true);
+    for (const file of files) {
+        for (const pattern of PII_PATTERNS) {
+            pattern.re.lastIndex = 0;
+            let match;
+            while ((match = pattern.re.exec(file.content)) !== null) {
+                const raw = match[0] ?? "";
+                if (pattern.id === "credit-card-like" && raw.replace(/\D/g, "").length < 13)
+                    continue;
+                const line = lineNumberAt(file.content, match.index);
+                const lineText = file.content.split(/\r?\n/)[line - 1] ?? "";
+                findings.push({
+                    id: pattern.id,
+                    label: pattern.label,
+                    truth: "INFERRED",
+                    evidence: [
+                        {
+                            path: file.relativePath,
+                            line,
+                            excerpt: redactPiiExcerpt(lineText, raw),
+                        },
+                    ],
+                });
+                if (findings.length >= 100)
+                    break;
+            }
+            if (findings.length >= 100)
+                break;
+        }
+        if (findings.length >= 100) {
+            limitations.push("PII finding cap reached (100)");
+            break;
+        }
+    }
+    const brain = await loadLatestBrain(root);
+    if (brain) {
+        const brainHits = searchBrain(brain, "email");
+        if (brainHits.length > 0) {
+            findings.push({
+                id: "brain-claim-hint",
+                label: "Project brain mentions email-related claims (review manually)",
+                truth: "INFERRED",
+                evidence: brainHits.slice(0, 3).map((h) => ({
+                    path: ".agentdoctor/project-brain",
+                    excerpt: h.text.slice(0, 100),
+                })),
+            });
+        }
+    }
+    else {
+        limitations.push("Project brain not available for supplemental search.");
+    }
+    return { root, findings, limitations };
+}

package/dist/product/requirements/trace.d.ts

@@ -0,0 +1,21 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface RequirementTrace {
+    id: string;
+    title: string;
+    sourcePath: string;
+    sourceLine: number;
+    acceptanceCriteria: string[];
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+    missingTestHeuristic: boolean;
+    missingTestNote?: string;
+}
+export interface RequirementsTraceReport {
+    root: string;
+    requirements: RequirementTrace[];
+    limitations: string[];
+}
+/**
+ * Scan repository docs for requirements / user stories with file evidence only.
+ */
+export declare function traceRequirements(rootInput: string, maxFileSizeBytes?: number): Promise<RequirementsTraceReport>;

package/dist/product/requirements/trace.js

@@ -0,0 +1,166 @@
+import path from "node:path";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
+import { readTextFile } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { isLikelyRequirementsDoc, isMarkdownDoc } from "../evidence-scan.js";
+const REQ_HEADING = /^(#{1,4})\s+(?:REQ[-\s]?(\d+)[:\s]+|Requirement\s+(\d+)[:\s]+|US[-\s]?(\d+)[:\s]+|User\s+Story\s+(\d+)[:\s]+)?(.+)$/i;
+const AC_LINE = /^\s*[-*]\s*(?:AC|Acceptance Criteria)[:\s]+(.+)$/i;
+const AC_SECTION = /^#{1,4}\s+Acceptance Criteria\s*$/i;
+function slugId(sourcePath, line, title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 40);
+    return `${sourcePath.replace(/[^\w./-]/g, "_")}:${line}:${slug || "req"}`;
+}
+function testFileMightCover(title, testPaths) {
+    const tokens = title
+        .toLowerCase()
+        .split(/\W+/)
+        .filter((t) => t.length > 3);
+    if (!tokens.length)
+        return false;
+    for (const tp of testPaths) {
+        const lower = tp.toLowerCase();
+        if (tokens.some((t) => lower.includes(t)))
+            return true;
+    }
+    return false;
+}
+function isTestPath(relativePath) {
+    const p = relativePath.toLowerCase();
+    return (p.includes(".test.") ||
+        p.includes(".spec.") ||
+        p.startsWith("tests/") ||
+        p.startsWith("test/") ||
+        p.includes("__tests__/"));
+}
+function docEligible(relativePath, content) {
+    if (!isMarkdownDoc(relativePath))
+        return false;
+    if (isLikelyRequirementsDoc(relativePath))
+        return true;
+    if (/acceptance criteria/i.test(content))
+        return true;
+    if (/^#{1,4}\s+(?:REQ|Requirement|User Story)/im.test(content))
+        return true;
+    return false;
+}
+function parseRequirementsFromDoc(relativePath, content, testPaths) {
+    const lines = content.split(/\r?\n/);
+    const out = [];
+    let inAcSection = false;
+    let current = null;
+    const flush = () => {
+        if (!current)
+            return;
+        if (current.acceptanceCriteria.length === 0) {
+            current.truth = "PARTIAL";
+        }
+        current.missingTestHeuristic = !testFileMightCover(current.title, testPaths);
+        if (current.missingTestHeuristic) {
+            current.missingTestNote =
+                "No test file path matched requirement title tokens (heuristic only).";
+        }
+        out.push(current);
+        current = null;
+        inAcSection = false;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const lineNo = i + 1;
+        if (AC_SECTION.test(line.trim())) {
+            inAcSection = true;
+            continue;
+        }
+        const heading = REQ_HEADING.exec(line.trim());
+        if (heading) {
+            flush();
+            const reqNum = heading[2] ?? heading[3] ?? heading[4] ?? heading[5];
+            const titlePart = (heading[6] ?? "").trim();
+            const base = relativePath.split("/").pop()?.toLowerCase() ?? "";
+            const explicitCatalog = base === "requirements.md" || base === "user-stories.md";
+            if (!reqNum && !explicitCatalog)
+                continue;
+            const title = reqNum ? titlePart : titlePart || line.replace(/^#{1,4}\s+/, "").trim();
+            if (!title || title.length < 3)
+                continue;
+            const displayTitle = reqNum ? `REQ-${reqNum}: ${title}` : title;
+            current = {
+                id: slugId(relativePath, lineNo, displayTitle),
+                title: displayTitle,
+                sourcePath: relativePath,
+                sourceLine: lineNo,
+                acceptanceCriteria: [],
+                truth: "VERIFIED",
+                evidence: [{ path: relativePath, line: lineNo, excerpt: line.trim().slice(0, 120) }],
+                missingTestHeuristic: false,
+            };
+            inAcSection = false;
+            continue;
+        }
+        if (!current)
+            continue;
+        const acInline = AC_LINE.exec(line);
+        if (acInline?.[1]) {
+            current.acceptanceCriteria.push(acInline[1].trim());
+            current.evidence.push({
+                path: relativePath,
+                line: lineNo,
+                excerpt: line.trim().slice(0, 120),
+            });
+            continue;
+        }
+        if (inAcSection && /^\s*[-*]\s+/.test(line)) {
+            const item = line.replace(/^\s*[-*]\s+/, "").trim();
+            if (item) {
+                current.acceptanceCriteria.push(item);
+                current.evidence.push({
+                    path: relativePath,
+                    line: lineNo,
+                    excerpt: item.slice(0, 120),
+                });
+            }
+        }
+        else if (inAcSection && line.trim() === "") {
+            continue;
+        }
+        else if (inAcSection && /^#{1,4}\s/.test(line)) {
+            inAcSection = false;
+        }
+    }
+    flush();
+    return out;
+}
+/**
+ * Scan repository docs for requirements / user stories with file evidence only.
+ */
+export async function traceRequirements(rootInput, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZE_BYTES) {
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const limitations = [
+        "Requirements are extracted only from markdown headings and acceptance-criteria sections present in files.",
+        "Missing-test detection is a filename/token heuristic, not coverage analysis.",
+    ];
+    if (detection.diagnostics.length) {
+        limitations.push(...detection.diagnostics.slice(0, 3));
+    }
+    const testPaths = detection.discovery.files.map((f) => f.relativePath).filter(isTestPath);
+    const requirements = [];
+    for (const entry of detection.discovery.files) {
+        const rel = entry.relativePath.replace(/\\/g, "/");
+        const abs = path.join(root, rel);
+        const text = await readTextFile(abs, maxFileSizeBytes);
+        if (text === null)
+            continue;
+        if (!docEligible(rel, text))
+            continue;
+        requirements.push(...parseRequirementsFromDoc(rel, text, testPaths));
+    }
+    requirements.sort((a, b) => a.sourcePath === b.sourcePath
+        ? a.sourceLine - b.sourceLine
+        : a.sourcePath.localeCompare(b.sourcePath));
+    return { root, requirements, limitations };
+}

package/dist/product/search/index.d.ts

@@ -0,0 +1,29 @@
+export interface IndexDocument {
+    id: string;
+    path: string;
+    text: string;
+}
+export interface TfidfIndex {
+    documents: IndexDocument[];
+    idf: Map<string, number>;
+    docVectors: Map<string, Map<string, number>>;
+    limitations: string[];
+}
+export declare function buildIndex(documents: IndexDocument[]): TfidfIndex;
+export declare function searchIndex(index: TfidfIndex, query: string, maxHits?: number): Array<{
+    document: IndexDocument;
+    score: number;
+}>;
+export declare function documentId(path: string, content: string): string;
+export declare function searchHybrid(index: TfidfIndex, query: string, substringHits: Array<{
+    path: string;
+    line?: number;
+    excerpt: string;
+    score: number;
+}>, maxHits?: number): Array<{
+    path: string;
+    line?: number;
+    excerpt: string;
+    score: number;
+    kind: "tfidf" | "keyword";
+}>;

package/dist/product/search/index.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+const TOKEN_RE = /[a-zA-Z][a-zA-Z0-9_]{1,48}|[0-9]+/g;
+function tokenize(text) {
+    const lower = text.toLowerCase();
+    const matches = lower.match(TOKEN_RE);
+    return matches ?? [];
+}
+function termFrequency(tokens) {
+    const tf = new Map();
+    for (const t of tokens) {
+        tf.set(t, (tf.get(t) ?? 0) + 1);
+    }
+    const max = Math.max(1, ...tf.values());
+    for (const [k, v] of tf) {
+        tf.set(k, v / max);
+    }
+    return tf;
+}
+export function buildIndex(documents) {
+    const limitations = [
+        "Local index uses keyword TF-IDF — not neural embeddings or semantic similarity.",
+    ];
+    const docTokens = new Map();
+    const df = new Map();
+    for (const doc of documents) {
+        const tokens = tokenize(doc.text);
+        docTokens.set(doc.id, tokens);
+        const unique = new Set(tokens);
+        for (const t of unique) {
+            df.set(t, (df.get(t) ?? 0) + 1);
+        }
+    }
+    const n = Math.max(1, documents.length);
+    const idf = new Map();
+    for (const [term, count] of df) {
+        idf.set(term, Math.log((1 + n) / (1 + count)) + 1);
+    }
+    const docVectors = new Map();
+    for (const doc of documents) {
+        const tf = termFrequency(docTokens.get(doc.id) ?? []);
+        const vec = new Map();
+        for (const [term, weight] of tf) {
+            const idfVal = idf.get(term) ?? 1;
+            vec.set(term, weight * idfVal);
+        }
+        docVectors.set(doc.id, vec);
+    }
+    return { documents, idf, docVectors, limitations };
+}
+function vectorNorm(vec) {
+    let sum = 0;
+    for (const v of vec.values())
+        sum += v * v;
+    return Math.sqrt(sum) || 1;
+}
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    const smaller = a.size <= b.size ? a : b;
+    const other = a.size <= b.size ? b : a;
+    for (const [term, weight] of smaller) {
+        const ow = other.get(term);
+        if (ow !== undefined)
+            dot += weight * ow;
+    }
+    return dot / (vectorNorm(a) * vectorNorm(b));
+}
+export function searchIndex(index, query, maxHits = 40) {
+    const qTokens = tokenize(query);
+    if (!qTokens.length)
+        return [];
+    const qTf = termFrequency(qTokens);
+    const qVec = new Map();
+    for (const [term, weight] of qTf) {
+        qVec.set(term, weight * (index.idf.get(term) ?? 1));
+    }
+    const hits = [];
+    for (const doc of index.documents) {
+        const dVec = index.docVectors.get(doc.id);
+        if (!dVec)
+            continue;
+        const score = cosineSimilarity(qVec, dVec);
+        if (score > 0)
+            hits.push({ document: doc, score });
+    }
+    hits.sort((a, b) => b.score - a.score || a.document.path.localeCompare(b.document.path));
+    return hits.slice(0, maxHits);
+}
+export function documentId(path, content) {
+    return createHash("sha1").update(`${path}\0${content.length}`).digest("hex").slice(0, 16);
+}
+export function searchHybrid(index, query, substringHits, maxHits = 40) {
+    const tfidf = searchIndex(index, query, maxHits);
+    const merged = new Map();
+    for (const h of tfidf) {
+        const key = h.document.path;
+        merged.set(key, {
+            path: h.document.path,
+            excerpt: h.document.text.slice(0, 140),
+            score: h.score + 0.05,
+            kind: "tfidf",
+        });
+    }
+    for (const h of substringHits) {
+        const key = `${h.path}:${h.line ?? 0}`;
+        const prev = merged.get(key);
+        if (!prev || h.score > prev.score) {
+            merged.set(key, { ...h, kind: "keyword" });
+        }
+        else if (prev) {
+            merged.set(key, { ...prev, score: prev.score + h.score * 0.5 });
+        }
+    }
+    return [...merged.values()]
+        .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+        .slice(0, maxHits);
+}

package/dist/product/search/software-search.d.ts

@@ -0,0 +1,19 @@
+import type { TruthLabel } from "../truth.js";
+export interface SoftwareSearchHit {
+    kind: "filename" | "content" | "brain" | "tfidf";
+    path: string;
+    line?: number;
+    excerpt: string;
+    score: number;
+    truth: TruthLabel;
+}
+export interface SoftwareSearchReport {
+    root: string;
+    query: string;
+    hits: SoftwareSearchHit[];
+    limitations: string[];
+}
+export declare function searchSymbolsAndConcepts(rootInput: string, query: string, options?: {
+    maxHits?: number;
+    maxFiles?: number;
+}): Promise<SoftwareSearchReport>;