srclawyer 0.6.0 → 0.6.2

package/README.md

@@ -90,6 +90,8 @@ Every finding traces back to a file and line (`src/engine/types.ts#Finding`).
 - **Data sent to a third party via a raw HTTP call isn't attributed to that processor.** SDK-integration detection (above) is anchored to known package imports. A call like Python's `requests.post("https://api.some-provider.com/...", json={...})` or JS's `fetch("https://api.some-provider.com/...")` — bypassing a dedicated SDK entirely — is invisible to this detection today, in both languages, regardless of how sensitive the data it sends is.
 - **Python support is based on one real-world corpus repository so far** (a Flask app; see `test-fixtures/golden-corpus/`), not the broader validation JS detection has had. Expect rougher edges on Flask codebases with unusual patterns.
 - **OpenAPI/Swagger scanning reports every schema under `components.schemas`, including response-only ones** — a schema that's only ever returned by the server (never submitted by a client) gets identical treatment to a real request-input schema, since nothing currently checks whether a schema is actually reachable from an operation's `requestBody` or `parameters`. On a large, schema-heavy spec this can mean a long "Items Requiring Manual Review" list that includes fields the product never collects, only ever returns. Separately, a schema defined **inline** inside a `requestBody` (not as a named, `$ref`'d `components.schemas` entry) isn't read at all today, in either direction — only named component schemas are scanned.
+- **Flask support covers direct request reads and same-function aliases only.** It detects `request.form[...]`, `request.args.get(...)`, `request.json[...]` and the like, plus one assignment hop within a function (`data = request.get_json()`, then `data['x']`). Form classes — Flask-WTF/WTForms `FlaskForm` subclasses with `StringField`/`PasswordField` declarations read via `form.email.data` — are not detected, and neither are fields rendered by template helpers such as `{{ form.email() }}`. A Flask app that collects data through WTForms may therefore show fewer collected fields than it actually has.
+- **Server-side template syntax inside HTML is not analyzed.** Jinja, Django, ERB and similar delimiters (`{{`, `{%`, `<%`, `{#`) are not interpreted: an inline `<script>` that isn't valid JavaScript until the template engine runs is skipped (listed in `--json` as `template-syntax`, with a one-line note), and form fields that a template generates rather than spells out as `<input>` tags are not seen.
 
 ## Network calls
 

package/dist/cli.js

@@ -16,9 +16,51 @@ program
     .version(version);
 program
     .command("init")
-    .description("One-time setup: jurisdiction, markets, industry")
-    .action(async () => {
-    await runInit(process.cwd());
+    .description("One-time setup: jurisdiction, markets, industry, and optional policy details (company info, data practices, regional rights)")
+    .option("--policy-details", "ask the optional policy-detail questions (company info, data practices, regional rights)")
+    .option("--no-policy-details", "skip all optional policy-detail questions, leaving them unanswered")
+    .option("--collects-childrens-data", "declare that this product knowingly collects data from children under 13/16")
+    .option("--no-collects-childrens-data", "declare that this product does not knowingly collect data from children under 13/16")
+    .option("--company-name <name>", "company or product name")
+    .option("--site-url <url>", "site or app URL")
+    .option("--privacy-contact-email <email>", "privacy contact email address")
+    .option("--eu-uk-users", "declare that this product has users in the EU/UK")
+    .option("--no-eu-uk-users", "declare that this product has no users in the EU/UK")
+    .option("--california-users", "declare that this product has users in California")
+    .option("--no-california-users", "declare that this product has no users in California")
+    .option("--sells-or-shares-data", "declare that personal data is sold or shared with third parties")
+    .option("--no-sells-or-shares-data", "declare that personal data is not sold or shared with third parties")
+    .option("--uses-data-for-advertising", "declare that personal data is used for advertising")
+    .option("--no-uses-data-for-advertising", "declare that personal data is not used for advertising")
+    .option("--data-retention-policy <text>", "how long personal data is retained")
+    .option("--account-deletion-instructions <text>", "how a user can delete their account or request data deletion")
+    .option("--minimum-age <number>", "minimum age required to use this product")
+    .option("--sends-data-to-ai-services", "declare that user data is sent to third-party AI services")
+    .option("--no-sends-data-to-ai-services", "declare that user data is not sent to third-party AI services")
+    .action(async (opts) => {
+    let minimumAge;
+    if (opts.minimumAge !== undefined) {
+        const parsed = Number(opts.minimumAge);
+        if (!Number.isInteger(parsed) || parsed < 0) {
+            program.error(`error: --minimum-age must be a whole, non-negative number (got "${opts.minimumAge}")`);
+        }
+        minimumAge = parsed;
+    }
+    await runInit(process.cwd(), {
+        policyDetails: opts.policyDetails,
+        collectsChildrensData: opts.collectsChildrensData,
+        companyName: opts.companyName,
+        siteUrl: opts.siteUrl,
+        privacyContactEmail: opts.privacyContactEmail,
+        euUkUsers: opts.euUkUsers,
+        californiaUsers: opts.californiaUsers,
+        sellsOrSharesData: opts.sellsOrSharesData,
+        usesDataForAdvertising: opts.usesDataForAdvertising,
+        dataRetentionPolicy: opts.dataRetentionPolicy,
+        accountDeletionInstructions: opts.accountDeletionInstructions,
+        minimumAge,
+        sendsDataToAiServices: opts.sendsDataToAiServices,
+    });
 });
 program
     .command("scan")

package/dist/commands/init.d.ts

@@ -1 +1,16 @@
-export declare function runInit(root: string): Promise<void>;
+export interface InitFlags {
+    policyDetails?: boolean;
+    collectsChildrensData?: boolean;
+    companyName?: string;
+    siteUrl?: string;
+    privacyContactEmail?: string;
+    euUkUsers?: boolean;
+    californiaUsers?: boolean;
+    sellsOrSharesData?: boolean;
+    usesDataForAdvertising?: boolean;
+    dataRetentionPolicy?: string;
+    accountDeletionInstructions?: string;
+    minimumAge?: number;
+    sendsDataToAiServices?: boolean;
+}
+export declare function runInit(root: string, flags?: InitFlags): Promise<void>;

package/dist/commands/init.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { CONFIG_FILENAME, DEFAULT_CONFIG, configPath, hasUnmigratedLegacyConfig, legacyConfigMessage, writeConfig, } from "../config/config.js";
 import { NETWORK_CALLS_NOTICE } from "../policy/legalNotices.js";
+import { runScan } from "./scan.js";
 function guessIndustry(root) {
     const pkgPath = join(root, "package.json");
     if (!existsSync(pkgPath))
@@ -24,16 +25,76 @@ async function ask(lines, question, fallback) {
     const answer = done ? "" : value.trim();
     return answer.length > 0 ? answer : fallback;
 }
-export async function runInit(root) {
+async function askOptional(lines, question) {
+    process.stdout.write(`${question} (optional, press Enter to skip): `);
+    const { value, done } = await lines.next();
+    const answer = done ? "" : value.trim();
+    return answer.length > 0 ? answer : null;
+}
+// suggested, when not null, is shown as the bracketed default and adopted on a blank answer -- used
+// to prefill EU/UK and California questions from targetMarkets without ever forcing an answer. When
+// suggested is null (no signal), blank means genuinely unanswered, same as every other optional field.
+async function askYesNoOptional(lines, question, suggested = null) {
+    const suffix = suggested === null ? " (y/n, optional, press Enter to skip)" : ` [${suggested ? "y" : "n"}]`;
+    process.stdout.write(`${question}${suffix}: `);
+    const { value, done } = await lines.next();
+    const answer = done ? "" : value.trim().toLowerCase();
+    if (answer.length === 0)
+        return suggested;
+    return /^y(es)?$/.test(answer);
+}
+async function askOptionalAge(lines, question) {
+    const raw = await askOptional(lines, question);
+    if (raw === null)
+        return null;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        console.log(`  (Could not read "${raw}" as a whole, non-negative number -- skipping. You can set this later by editing ${CONFIG_FILENAME}.)`);
+        return null;
+    }
+    return parsed;
+}
+// Generic resolution order for every new optional field: an explicit flag always wins outright;
+// otherwise the field is only asked if the policy-details gate resolved to yes; otherwise it's null.
+async function resolveField(flagValue, gateYes, askFn) {
+    if (flagValue !== undefined)
+        return flagValue;
+    if (!gateYes)
+        return null;
+    return askFn();
+}
+const EU_UK_TOKENS = new Set(["eu", "uk", "gb", "eea", "european union", "united kingdom"]);
+const CALIFORNIA_TOKENS = new Set(["ca", "california", "us-ca"]);
+function targetMarketsSuggestEuUk(markets) {
+    return markets.some((m) => EU_UK_TOKENS.has(m.trim().toLowerCase()));
+}
+function targetMarketsSuggestCalifornia(markets) {
+    return markets.some((m) => CALIFORNIA_TOKENS.has(m.trim().toLowerCase()));
+}
+// Only warns in the one direction that's a real contradiction: target markets signal a region, but
+// the final answer explicitly denies it. The reverse (no signal, but the user says yes) isn't a
+// contradiction -- targetMarkets is free text and was never meant to be an exhaustive jurisdiction
+// list. Never blocks or overrides -- the explicit answer always stands, this only warns.
+function warnIfContradictsTargetMarkets(label, finalValue, suggestedFromMarkets) {
+    if (suggestedFromMarkets && finalValue === false) {
+        console.log(`\nWarning: your target markets suggest ${label} users, but you indicated none -- the generated policy will omit ${label}-specific disclosures. Re-run init or edit ${CONFIG_FILENAME} if this is incorrect.\n`);
+    }
+}
+export async function runInit(root, flags = {}) {
     const existingPath = configPath(root);
     if (existsSync(existingPath)) {
-        console.log(`${CONFIG_FILENAME} already exists. Delete it first if you want to redo setup.`);
+        console.log(`${CONFIG_FILENAME} already exists -- left unchanged. To start over, delete it and re-run "srclawyer init":\n\n  rm ${CONFIG_FILENAME}\n  srclawyer init\n`);
         return;
     }
     if (hasUnmigratedLegacyConfig(root)) {
         console.log(legacyConfigMessage());
         return;
     }
+    // The final "run a scan now?" prompt below is interactive-only: skipped whenever this run is
+    // flag-driven (any flag was passed -- a scripted/CI invocation, even a partial one) or stdin isn't
+    // a real TTY (piped, redirected, non-interactive). Computed once, up front, rather than re-checked
+    // at the end, since nothing between here and there changes either condition.
+    const isInteractive = process.stdin.isTTY === true && Object.values(flags).every((v) => v === undefined);
     const guessedIndustry = guessIndustry(root);
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const lines = rl[Symbol.asyncIterator]();
@@ -43,37 +104,75 @@ export async function runInit(root) {
     console.log("SrcLawyer setup — answered once, reused on every scan.\n");
     const entityLocation = await ask(lines, "Where is your legal entity located? (country)", DEFAULT_CONFIG.entityLocation ?? "");
     const targetMarketsRaw = await ask(lines, "Which regions/markets do you serve? (comma-separated, e.g. US, EU)", "");
+    const targetMarkets = targetMarketsRaw.split(",").map((s) => s.trim()).filter(Boolean);
     const industry = await ask(lines, "What industry/vertical is this product in?", guessedIndustry ?? "");
-    const childrensDataRaw = await ask(lines, "Does this product knowingly collect data from children under 13/16?", "no");
+    const gateYes = flags.policyDetails !== undefined
+        ? flags.policyDetails
+        : /^y(es)?$/i.test((await ask(lines, "Add privacy policy details now? (company info, data practices, regional rights, etc.)", "y")).trim());
+    // Deliberately requires an explicit y/n -- a bare Enter, empty stdin, or a declined gate must leave
+    // this null (unanswered, rendered as a placeholder), never silently "no". Unlike askOptional's other
+    // callers, there is no safe default here: "no" is itself a real, consequential legal declaration, not
+    // a neutral fallback. Layer 2's high-stakes override (scan.ts) coerces null to false at its one call
+    // site, so leaving this unanswered never weakens that safety check -- see childrensDataOverride.test.ts.
+    const collectsChildrensData = await resolveField(flags.collectsChildrensData, gateYes, () => askYesNoOptional(lines, "Does this product knowingly collect data from children under 13/16?"));
+    const minimumAge = await resolveField(flags.minimumAge, gateYes, () => askOptionalAge(lines, "Minimum age required to use this product"));
+    const companyName = await resolveField(flags.companyName, gateYes, () => askOptional(lines, "Company or product name"));
+    const siteUrl = await resolveField(flags.siteUrl, gateYes, () => askOptional(lines, "Site or app URL"));
+    const privacyContactEmail = await resolveField(flags.privacyContactEmail, gateYes, () => askOptional(lines, "Privacy contact email"));
+    const euUkSuggested = targetMarketsSuggestEuUk(targetMarkets);
+    const hasEuUkUsers = await resolveField(flags.euUkUsers, gateYes, () => askYesNoOptional(lines, "Do you have users in the EU/UK?", euUkSuggested ? true : null));
+    warnIfContradictsTargetMarkets("EU/UK", hasEuUkUsers, euUkSuggested);
+    const californiaSuggested = targetMarketsSuggestCalifornia(targetMarkets);
+    const hasCaliforniaUsers = await resolveField(flags.californiaUsers, gateYes, () => askYesNoOptional(lines, "Do you have users in California?", californiaSuggested ? true : null));
+    warnIfContradictsTargetMarkets("California", hasCaliforniaUsers, californiaSuggested);
+    const sellsOrSharesData = await resolveField(flags.sellsOrSharesData, gateYes, () => askYesNoOptional(lines, "Does this product sell or share personal data with third parties?"));
+    const usesDataForAdvertising = await resolveField(flags.usesDataForAdvertising, gateYes, () => askYesNoOptional(lines, "Does this product use personal data for advertising?"));
+    const dataRetentionPolicy = await resolveField(flags.dataRetentionPolicy, gateYes, () => askOptional(lines, "How long is personal data retained?"));
+    const accountDeletionInstructions = await resolveField(flags.accountDeletionInstructions, gateYes, () => askOptional(lines, "How can a user delete their account or request data deletion?"));
+    // Deliberately about the SCANNED PRODUCT's own behavior (does it send its end-users' data to AI
+    // services as part of its own functionality) -- not about SrcLawyer's own, separately-documented
+    // BYOK network calls described in NETWORK_CALLS_NOTICE above.
+    const sendsDataToAiServices = await resolveField(flags.sendsDataToAiServices, gateYes, () => askYesNoOptional(lines, "Does this product send user data to third-party AI services (e.g. OpenAI, Anthropic) as part of its own functionality?"));
     // "managed" is deliberately not offered here -- it's a real SrcLawyerTier value and config.ts/
     // resolveProviderForTier.ts both still support it fully (a hand-edited config with tier: managed
     // still gets a clear, accurate error at scan time), but there's no advertised path to it from this
     // prompt, so a tester reading the choices here can't select a dead end during setup.
-    const tierRaw = await ask(lines, "Tier: free (static analysis only) / byok (bring your own Anthropic key)", "free");
-    const tier = normalizeTier(tierRaw);
+    const enableByokRaw = await ask(lines, "Enable optional AI-assisted review with your own Anthropic key? (advanced)", "n");
+    const tier = /^y(es)?$/i.test(enableByokRaw.trim()) ? "byok" : "free";
     let apiKeyEnvVar = null;
     if (tier === "byok") {
         apiKeyEnvVar = await ask(lines, "Which environment variable holds your Anthropic API key?", "ANTHROPIC_API_KEY");
         console.log(`\nNote: only the name "${apiKeyEnvVar}" is written to ${CONFIG_FILENAME} — the key itself is never written to disk. It's read from your environment at scan time.`);
     }
-    else if (tier === "managed") {
-        console.log("\nHeads up: the managed tier's hosted backend isn't available yet. Layer 1 (static analysis) will still run fine; AI-assisted resolution will report a clear error until it ships.");
-    }
-    rl.close();
     const config = {
         entityLocation: entityLocation || null,
-        targetMarkets: targetMarketsRaw.split(",").map((s) => s.trim()).filter(Boolean),
+        targetMarkets,
         industry: industry || null,
-        collectsChildrensData: /^y(es)?$/i.test(childrensDataRaw.trim()),
+        collectsChildrensData,
         tier,
         ...(tier === "byok" ? { llm: { provider: "anthropic", apiKeyEnvVar } } : {}),
+        companyName,
+        siteUrl,
+        privacyContactEmail,
+        hasEuUkUsers,
+        hasCaliforniaUsers,
+        sellsOrSharesData,
+        usesDataForAdvertising,
+        dataRetentionPolicy,
+        accountDeletionInstructions,
+        minimumAge,
+        sendsDataToAiServices,
     };
     writeConfig(root, config);
     console.log(`\nWrote ${CONFIG_FILENAME}. Run "srclawyer scan" to analyze this codebase.`);
-}
-function normalizeTier(raw) {
-    const normalized = raw.trim().toLowerCase();
-    if (normalized === "byok" || normalized === "managed")
-        return normalized;
-    return "free";
+    let runScanNow = false;
+    if (isInteractive) {
+        const raw = await ask(lines, "Run a scan now and generate your policy?", "y");
+        runScanNow = /^y(es)?$/i.test(raw.trim());
+    }
+    rl.close();
+    if (runScanNow) {
+        console.log("");
+        await runScan(root, { json: false, out: "PRIVACY_POLICY.md", llm: true });
+    }
 }

package/dist/commands/scan.js

@@ -24,6 +24,12 @@ export async function runScan(root, options) {
     }
     const result = await scan(root);
     let findings = result.findings;
+    if (result.workspaceWarning)
+        console.error(result.workspaceWarning);
+    if (result.skippedFilesWarning)
+        console.error(result.skippedFilesWarning);
+    if (result.templateSyntaxNote)
+        console.error(result.templateSyntaxNote);
     if (result.maxZodFragmentBytes > 0) {
         console.error(`Largest Zod-schema fragment this scan: ${result.maxZodFragmentBytes} bytes (hard ceiling: ${MAX_FRAGMENT_BYTES} bytes).`);
     }
@@ -56,7 +62,11 @@ export async function runScan(root, options) {
                 }
                 console.log(`Sending ${ambiguous.length} ambiguous item(s) to ${provider.name}...`);
                 const resolved = await resolveAmbiguousFindings(ambiguous, provider, {
-                    collectsChildrensData: config.collectsChildrensData,
+                    // Preserves today's exact override behavior bit-for-bit: a missing/legacy key already
+                    // behaved as false before collectsChildrensData became nullable. Only the generated
+                    // document (generatePolicy.ts) distinguishes "explicitly no" from "never answered" -- this
+                    // safety-critical override is unchanged.
+                    collectsChildrensData: config.collectsChildrensData ?? false,
                 });
                 const resolvedById = new Map(resolved.map((f) => [f.id, f]));
                 findings = findings.map((f) => resolvedById.get(f.id) ?? f);
@@ -67,7 +77,7 @@ export async function runScan(root, options) {
     const finalResult = { ...result, findings, ambiguousCount };
     const policyPath = resolve(root, options.out);
     writeFileSync(policyPath, generatePolicyMarkdown(finalResult, config, llmError, protectedLogicWarning));
-    if (result.unsupportedStackWarning || llmError || protectedLogicWarning || legacyConfigWarning) {
+    if (result.unsupportedStackWarning || result.workspaceWarning || result.skippedFilesWarning || llmError || protectedLogicWarning || legacyConfigWarning) {
         process.exitCode = 1;
     }
     if (options.json) {

package/dist/config/config.d.ts

@@ -10,9 +10,20 @@ export interface SrcLawyerConfig {
     entityLocation: string | null;
     targetMarkets: string[];
     industry: string | null;
-    collectsChildrensData: boolean;
+    collectsChildrensData: boolean | null;
     tier?: SrcLawyerTier;
     llm?: SrcLawyerLlmConfig;
+    companyName?: string | null;
+    siteUrl?: string | null;
+    privacyContactEmail?: string | null;
+    hasEuUkUsers?: boolean | null;
+    hasCaliforniaUsers?: boolean | null;
+    sellsOrSharesData?: boolean | null;
+    usesDataForAdvertising?: boolean | null;
+    dataRetentionPolicy?: string | null;
+    accountDeletionInstructions?: string | null;
+    minimumAge?: number | null;
+    sendsDataToAiServices?: boolean | null;
 }
 export declare const DEFAULT_CONFIG: SrcLawyerConfig;
 export declare function configPath(root: string): string;

package/dist/config/config.js

@@ -8,8 +8,19 @@ export const DEFAULT_CONFIG = {
     entityLocation: null,
     targetMarkets: [],
     industry: null,
-    collectsChildrensData: false,
+    collectsChildrensData: null,
     tier: "free",
+    companyName: null,
+    siteUrl: null,
+    privacyContactEmail: null,
+    hasEuUkUsers: null,
+    hasCaliforniaUsers: null,
+    sellsOrSharesData: null,
+    usesDataForAdvertising: null,
+    dataRetentionPolicy: null,
+    accountDeletionInstructions: null,
+    minimumAge: null,
+    sendsDataToAiServices: null,
 };
 export function configPath(root) {
     return join(root, CONFIG_FILENAME);

package/dist/engine/discoverFiles.d.ts

@@ -1,3 +1,4 @@
+import type { RootBoundary } from "./rootBoundary.js";
 export interface DiscoveredFiles {
     codeFiles: string[];
     pythonFiles: string[];
@@ -5,4 +6,4 @@ export interface DiscoveredFiles {
     schemaFiles: string[];
     manifestFiles: string[];
 }
-export declare function discoverFiles(root: string): Promise<DiscoveredFiles>;
+export declare function discoverFiles(root: string, boundary: RootBoundary): Promise<DiscoveredFiles>;

package/dist/engine/discoverFiles.js

@@ -1,4 +1,4 @@
-import fg from "fast-glob";
+import { globFiles } from "./globFiles.js";
 const CODE_PATTERNS = ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.mjs", "**/*.cjs"];
 const PYTHON_PATTERNS = ["**/*.py"];
 const HTML_PATTERNS = ["**/*.html", "**/*.htm"];
@@ -27,13 +27,13 @@ const PYTHON_IGNORE = [
     "**/test_*.py",
     "**/*_test.py",
 ];
-export async function discoverFiles(root) {
+export async function discoverFiles(root, boundary) {
     const [codeFiles, pythonFiles, htmlFiles, schemaFiles, manifestFiles] = await Promise.all([
-        fg(CODE_PATTERNS, { cwd: root, absolute: true, ignore: IGNORE, dot: false }),
-        fg(PYTHON_PATTERNS, { cwd: root, absolute: true, ignore: PYTHON_IGNORE, dot: false }),
-        fg(HTML_PATTERNS, { cwd: root, absolute: true, ignore: IGNORE, dot: false }),
-        fg(SCHEMA_PATTERNS, { cwd: root, absolute: true, ignore: ["**/node_modules/**"], dot: false }),
-        fg(MANIFEST_PATTERNS, { cwd: root, absolute: true, ignore: ["**/node_modules/**"], dot: false }),
+        globFiles(CODE_PATTERNS, { cwd: root, absolute: true, ignore: IGNORE, dot: false, boundary }),
+        globFiles(PYTHON_PATTERNS, { cwd: root, absolute: true, ignore: PYTHON_IGNORE, dot: false, boundary }),
+        globFiles(HTML_PATTERNS, { cwd: root, absolute: true, ignore: IGNORE, dot: false, boundary }),
+        globFiles(SCHEMA_PATTERNS, { cwd: root, absolute: true, ignore: ["**/node_modules/**"], dot: false, boundary }),
+        globFiles(MANIFEST_PATTERNS, { cwd: root, absolute: true, ignore: ["**/node_modules/**"], dot: false, boundary }),
     ]);
     return { codeFiles, pythonFiles, htmlFiles, schemaFiles, manifestFiles };
 }

package/dist/engine/discoverProjects.d.ts

@@ -1,3 +1,11 @@
+import type { RootBoundary } from "./rootBoundary.js";
 import type { ProjectManifest } from "./types.js";
-export declare function discoverProjects(root: string): Promise<ProjectManifest[]>;
+export interface ProjectDiscovery {
+    projects: ProjectManifest[];
+    /** Non-null when the scanned repo's own workspace config was rejected (malformed, hostile, or too
+     *  expensive to expand) and the default package locations were scanned instead -- surfaced on the
+     *  console and in the generated policy, since the scan may then be incomplete. */
+    workspaceWarning: string | null;
+}
+export declare function discoverProjects(root: string, boundary: RootBoundary): Promise<ProjectDiscovery>;
 export declare function describeProject(root: string, project: ProjectManifest): string;

package/dist/engine/discoverProjects.js

@@ -1,32 +1,85 @@
 import { readFileSync, existsSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
-import fg from "fast-glob";
-export async function discoverProjects(root) {
+import { globFiles } from "./globFiles.js";
+import { validateWorkspacePatterns } from "./workspacePatterns.js";
+const DEFAULT_WORKSPACE_PATTERNS = ["packages/*", "apps/*"];
+function rejectedConfigWarning(reason) {
+    return `Workspace configuration in package.json was rejected (${reason}); the default package locations (${DEFAULT_WORKSPACE_PATTERNS.join(", ")}) were scanned instead, so this scan may be incomplete.`;
+}
+function readPackageJson(path, boundary) {
+    if (!boundary.allowsPath(path))
+        return { error: "package.json resolves outside the scanned root" };
+    try {
+        // A leading BOM (common from Windows editors) is valid in practice but not to JSON.parse.
+        const text = readFileSync(path, "utf8").replace(/^/, "");
+        return { value: JSON.parse(text) };
+    }
+    catch {
+        return { error: "package.json could not be parsed" };
+    }
+}
+// undefined means "no workspace config at all"; anything else (including a wrong type) is handed to
+// the validator, which rejects what isn't an array of well-formed patterns.
+function rawWorkspaces(pkg) {
+    const workspaces = typeof pkg === "object" && pkg !== null ? pkg.workspaces : undefined;
+    if (workspaces === undefined || workspaces === null)
+        return undefined;
+    if (typeof workspaces === "object" && !Array.isArray(workspaces))
+        return workspaces.packages ?? undefined;
+    return workspaces;
+}
+async function globManifests(patterns, root, boundary) {
+    return globFiles(patterns.map((p) => (p.startsWith("!") ? `!${join(p.slice(1), "package.json")}` : join(p, "package.json"))), { cwd: root, absolute: true, ignore: ["**/node_modules/**"], boundary });
+}
+export async function discoverProjects(root, boundary) {
     const rootPackageJsonPath = join(root, "package.json");
     if (!existsSync(rootPackageJsonPath)) {
-        return [{ root, kind: "unknown", manifestPath: null }];
-    }
-    const rootPackageJson = JSON.parse(readFileSync(rootPackageJsonPath, "utf8"));
-    const workspacePatterns = Array.isArray(rootPackageJson.workspaces)
-        ? rootPackageJson.workspaces
-        : rootPackageJson.workspaces?.packages;
-    const lernaPath = join(root, "lerna.json");
-    const nxPath = join(root, "nx.json");
-    const hasWorkspaceConfig = Boolean(workspacePatterns) || existsSync(lernaPath) || existsSync(nxPath);
+        return { projects: [{ root, kind: "unknown", manifestPath: null }], workspaceWarning: null };
+    }
+    const rootProject = { root, kind: "node", manifestPath: rootPackageJsonPath };
+    const parsed = readPackageJson(rootPackageJsonPath, boundary);
+    let workspaceWarning = null;
+    let patterns = null;
+    let hasWorkspaceConfig = existsSync(join(root, "lerna.json")) || existsSync(join(root, "nx.json"));
+    if ("error" in parsed) {
+        workspaceWarning = rejectedConfigWarning(parsed.error);
+        hasWorkspaceConfig = true;
+    }
+    else {
+        const raw = rawWorkspaces(parsed.value);
+        if (raw !== undefined) {
+            hasWorkspaceConfig = true;
+            const validation = validateWorkspacePatterns(raw);
+            if (validation.ok)
+                patterns = validation.patterns;
+            else
+                workspaceWarning = rejectedConfigWarning(validation.reason);
+        }
+    }
     if (!hasWorkspaceConfig) {
-        return [{ root, kind: "node", manifestPath: rootPackageJsonPath }];
+        return { projects: [rootProject], workspaceWarning: null };
+    }
+    let manifestPaths;
+    try {
+        manifestPaths = await globManifests(patterns ?? DEFAULT_WORKSPACE_PATTERNS, root, boundary);
+    }
+    catch {
+        // Belt and braces behind validateWorkspacePatterns: a pattern that still fails to expand must
+        // never take the whole scan down.
+        workspaceWarning = rejectedConfigWarning("the patterns could not be expanded");
+        try {
+            manifestPaths = await globManifests(DEFAULT_WORKSPACE_PATTERNS, root, boundary);
+        }
+        catch {
+            manifestPaths = [];
+        }
     }
-    const patterns = workspacePatterns ?? ["packages/*", "apps/*"];
-    const manifestPaths = await fg(patterns.map((p) => join(p, "package.json")), { cwd: root, absolute: true, ignore: ["**/node_modules/**"] });
     const projects = manifestPaths.map((manifestPath) => ({
         root: dirname(manifestPath),
         kind: "node",
         manifestPath,
     }));
-    if (projects.length === 0) {
-        return [{ root, kind: "node", manifestPath: rootPackageJsonPath }];
-    }
-    return projects;
+    return { projects: projects.length === 0 ? [rootProject] : projects, workspaceWarning };
 }
 export function describeProject(root, project) {
     const rel = relative(root, project.root);

package/dist/engine/globFiles.d.ts

@@ -0,0 +1,10 @@
+import type { RootBoundary } from "./rootBoundary.js";
+export interface GlobFilesOptions {
+    cwd: string;
+    absolute?: boolean;
+    ignore?: string[];
+    dot?: boolean;
+    /** When given, symlinks resolving outside the scanned root are neither walked nor returned. */
+    boundary?: RootBoundary;
+}
+export declare function globFiles(patterns: string | string[], options: GlobFilesOptions): Promise<string[]>;

package/dist/engine/globFiles.js

@@ -0,0 +1,12 @@
+import { glob } from "tinyglobby";
+// expandDirectories: false keeps tinyglobby's matching identical to the fast-glob behavior this
+// replaced (a pattern matches only what it names, never everything under a matched directory).
+// tinyglobby/picomatch compiles braces to regex alternation rather than expanding them, so it has no
+// equivalent of the `braces` package's stack-overflow/memory exposure (GHSA-vfj7-8cjw-p6xm); patterns
+// that come from a scanned repo are still bounded first, in workspacePatterns.ts.
+// Sorted so scan order (and therefore the order of findings in reports) doesn't depend on filesystem
+// traversal order, which neither fast-glob nor tinyglobby guarantees.
+export async function globFiles(patterns, options) {
+    const { boundary, ...globOptions } = options;
+    return (await glob(patterns, { expandDirectories: false, ...globOptions, ...(boundary ? { fs: boundary.globFs() } : {}) })).sort();
+}

package/dist/engine/languageDetection.d.ts

@@ -1 +1,2 @@
-export declare function detectUnsupportedStack(root: string): Promise<string | null>;
+import type { RootBoundary } from "./rootBoundary.js";
+export declare function detectUnsupportedStack(root: string, boundary: RootBoundary): Promise<string | null>;

package/dist/engine/languageDetection.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import fg from "fast-glob";
+import { globFiles } from "./globFiles.js";
 const IGNORE = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**", "**/vendor/**", "**/venv/**", "**/.venv/**", "**/__pycache__/**"];
 // Python moved from UNSUPPORTED_LANGUAGES to here once Flask detection shipped (Stage A) -- it's a
 // supported *language* now, but only one framework within it is actually understood. A Python project
@@ -17,7 +17,7 @@ const FASTAPI_IMPORT = /\bfrom\s+fastapi\b|\bimport\s+fastapi\b/;
 function bannerize(message) {
     return `UNSUPPORTED CODEBASE — ${message} SrcLawyer only analyzes JavaScript/TypeScript, HTML, and Flask-based Python today; the findings below (if any) are incomplete and MUST NOT be treated as a full compliance scan.`;
 }
-async function detectFrameworkSignature(root) {
+async function detectFrameworkSignature(root, boundary) {
     if (existsSync(join(root, "manage.py"))) {
         return bannerize("Django detected (manage.py found at the project root) — Django support isn't built yet.");
     }
@@ -26,7 +26,7 @@ async function detectFrameworkSignature(root) {
     if (hasGemfile && hasRailsLayout) {
         return bannerize("Rails detected (Gemfile + a Rails app/config layout found).");
     }
-    const protoFiles = await fg("**/*.proto", { cwd: root, ignore: IGNORE, dot: false });
+    const protoFiles = await globFiles("**/*.proto", { cwd: root, ignore: IGNORE, dot: false, boundary });
     if (protoFiles.length > 0) {
         return bannerize(`gRPC/Protocol Buffers detected (${protoFiles.length} .proto file(s) found) — protobuf schemas are not parsed.`);
     }
@@ -53,10 +53,10 @@ async function detectUnsupportedPythonFramework(root, pythonFiles) {
     }
     return null;
 }
-async function detectDominantUnsupportedLanguage(root) {
+async function detectDominantUnsupportedLanguage(root, boundary) {
     const [supportedFiles, ...unsupportedGroups] = await Promise.all([
-        fg(SUPPORTED_EXTENSIONS.map((ext) => `**/*.${ext}`), { cwd: root, ignore: IGNORE, dot: false }),
-        ...UNSUPPORTED_LANGUAGES.map((lang) => fg(lang.extensions.map((ext) => `**/*.${ext}`), { cwd: root, ignore: IGNORE, dot: false })),
+        globFiles(SUPPORTED_EXTENSIONS.map((ext) => `**/*.${ext}`), { cwd: root, ignore: IGNORE, dot: false, boundary }),
+        ...UNSUPPORTED_LANGUAGES.map((lang) => globFiles(lang.extensions.map((ext) => `**/*.${ext}`), { cwd: root, ignore: IGNORE, dot: false, boundary })),
     ]);
     const counts = UNSUPPORTED_LANGUAGES.map((lang, i) => ({ label: lang.label, count: unsupportedGroups[i].length }));
     const dominant = counts.filter((c) => c.count > 0).sort((a, b) => b.count - a.count)[0];
@@ -64,15 +64,15 @@ async function detectDominantUnsupportedLanguage(root) {
         return null;
     return bannerize(`${dominant.label} detected as the primary language (${dominant.count} file(s), vs ${supportedFiles.length} supported file(s)).`);
 }
-export async function detectUnsupportedStack(root) {
-    const frameworkWarning = await detectFrameworkSignature(root);
+export async function detectUnsupportedStack(root, boundary) {
+    const frameworkWarning = await detectFrameworkSignature(root, boundary);
     if (frameworkWarning)
         return frameworkWarning;
-    const pythonFiles = await fg("**/*.py", { cwd: root, absolute: true, ignore: IGNORE, dot: false });
+    const pythonFiles = await globFiles("**/*.py", { cwd: root, absolute: true, ignore: IGNORE, dot: false, boundary });
     if (pythonFiles.length > 0) {
         const pythonFrameworkWarning = await detectUnsupportedPythonFramework(root, pythonFiles);
         if (pythonFrameworkWarning)
             return pythonFrameworkWarning;
     }
-    return detectDominantUnsupportedLanguage(root);
+    return detectDominantUnsupportedLanguage(root, boundary);
 }

package/dist/engine/rootBoundary.d.ts

@@ -0,0 +1,29 @@
+import { realpath, realpathSync } from "node:fs";
+/**
+ * The scanned root as a security boundary: a scanned repo is untrusted input, so no file whose REAL
+ * path resolves outside it may be read, and no directory symlink leaving it may be walked (a symlink
+ * to "/" or "~" would otherwise make a scan traverse the whole filesystem and report lines from files
+ * the repo's author chose). In-root symlinks, including loops that stay inside, keep working.
+ */
+export declare class RootBoundary {
+    readonly root: string;
+    readonly realRoot: string;
+    private readonly blocked;
+    private readonly resolved;
+    constructor(root: string);
+    isInsideRealPath(resolved: string): boolean;
+    /** Records a blocked link by its in-repo (lexical) path only -- never its target. */
+    private recordBlocked;
+    /** Read-time check, independent of how the path was discovered: the real path if it is inside the
+     *  root, else null (and an out-of-root link is recorded). Unresolvable paths fail closed. Cached. */
+    resolveInside(path: string): string | null;
+    allowsPath(path: string): boolean;
+    /** `fs` overrides for tinyglobby: a symlink resolving outside the root errors out, so it is neither
+     *  walked (directories) nor returned (files). */
+    globFs(): {
+        realpath: typeof realpath;
+        realpathSync: typeof realpathSync;
+    };
+    /** Relative in-repo paths of every blocked link, sorted; call after discovery and reading are done. */
+    blockedLinks(): string[];
+}