srclawyer 0.7.0 → 0.8.0

package/README.md

@@ -23,10 +23,44 @@ srclawyer init
 srclawyer scan                  # analyze the codebase and write PRIVACY_POLICY.md
 srclawyer scan --json           # findings as JSON (still writes the policy file)
 srclawyer scan --out docs/privacy.md
+srclawyer scan --force          # overwrite the policy even if it was edited (see below)
 ```
 
 If `srclawyer` isn't found right after a global install, see [Troubleshooting: command not found](#troubleshooting-command-not-found) below.
 
+## Editing the generated policy
+
+`scan` regenerates `PRIVACY_POLICY.md` freely **until you edit it**. After that the file is yours, and `scan` will not overwrite it.
+
+The generated policy has `[TO COMPLETE: …]` placeholders for facts only you know (company name, contact email, retention period, and so on). Fill them in by answering the `init` questions or by setting the same fields in `.srclawyer.config.yml`, then re-run `scan`: the placeholders are replaced. Once you have changed the file by hand (filled a placeholder in the text, reworded a section, anything), it is no longer the generated version, so complete the rest by hand too.
+
+How it works: every generated policy ends with a marker line, `<!-- srclawyer:policy-sha256=… -->`, holding a hash of the rest of the file. Before writing, `scan` recomputes the hash.
+
+| The existing file | What `scan` does |
+|---|---|
+| doesn't exist, or still matches its marker | writes the new policy |
+| edited since it was generated | refuses (see below) |
+| has no marker | refuses (see below) |
+| any of the above, with `--force` | overwrites it |
+
+When it refuses, a plain `scan` exits 2 before scanning anything, and prints one of these:
+
+```text
+Not overwriting PRIVACY_POLICY.md: it has been edited since SrcLawyer generated it. Write the new policy to a separate file with --out PRIVACY_POLICY.generated.md and compare, or pass --force to replace it.
+```
+
+```text
+Not overwriting PRIVACY_POLICY.md: it was not generated by this version of SrcLawyer (it may be hand-written, or generated before overwrite protection was added in 0.8.0). Write the new policy to a separate file with --out PRIVACY_POLICY.generated.md and compare, or pass --force to replace it.
+```
+
+- **`--out` is guarded the same way.** `srclawyer scan --out PRIVACY_POLICY.generated.md` writes a draft you can compare with your edited policy; running it again overwrites that draft cleanly as long as you haven't edited the draft.
+- **`scan --write-inventory`** still writes the drift baseline when your policy is protected. It leaves the policy untouched, says so, and exits 0. So "update the policy by hand, then refresh the baseline" works without `--force`.
+- **`init`** never overwrites a policy. If `PRIVACY_POLICY.md` is already there and would be refused, it skips its "run a scan now?" question and prints the `--out` command instead.
+- **The marker is an HTML comment.** It is invisible when the Markdown is rendered, but it is in the file's raw text and in the page source if you publish the Markdown as is. You can delete the line, and nothing breaks, but the file then counts as not generated by SrcLawyer and is protected from then on.
+- **Formatters count as edits.** If a formatter (Prettier, a Markdown auto-fix hook) rewrites the file, it no longer matches its marker. `scan` fails safe: it refuses, and you use `--out` or `--force`.
+
+**Upgrading from 0.7.0 or earlier.** Policies generated before 0.8.0 have no marker, so the first `scan` after upgrading refuses to overwrite one, even if you never edited it. If you never touched it, run `srclawyer scan --force` once; from then on it carries a marker. If you did edit it, run `srclawyer scan --out PRIVACY_POLICY.generated.md` and compare the two files.
+
 ## Development
 
 Working on SrcLawyer itself (not just using it):
@@ -122,15 +156,15 @@ Only the variable's *name* is stored in the config — the key itself is never w
 **Free during the beta.** Flags when your code starts collecting a new kind of data, or using a new third-party processor, that your privacy policy was never updated for. It compares the code against a committed baseline, `.srclawyer.inventory.json` — just the sorted data categories and processors, no file names or line numbers — not against policy text, which people edit by hand.
 
 ```bash
-npx srclawyer scan --write-inventory     # once: writes the policy and the baseline; commit the baseline
+npx srclawyer scan --write-inventory     # once: writes the policy (if safe to) and the baseline; commit the baseline
 npx srclawyer check                      # exit 0 no drift, 1 drift, 2 error, 3 inconclusive
 ```
 
 ```yaml
 - uses: actions/checkout@v7
-- uses: SrcLawyer/srclawyer@v0.7.0
+- uses: SrcLawyer/srclawyer@v0.8.0
   with:
-    srclawyer-version: 0.7.0             # required and pinned
+    srclawyer-version: 0.8.0             # required and pinned
 ```
 
 Drift fails the check, and the step summary lists what was added and removed with a one-line fix. If no verdict can be reached — the confidence service is unreachable, files were skipped, or the baseline and the run used different file discovery — the result is **inconclusive**, a warning by default, and is never reported as drift. The Action needs no secrets and `contents: read`; an optional pull-request comment needs `pull-requests: write`. Inside a git repository, `check` and `--write-inventory` look only at tracked and untracked-but-not-ignored files, so a gitignored build directory can't cause phantom drift; plain `scan` is unchanged. `check` makes the same network calls as `scan` (below) and never calls an AI provider.
@@ -144,6 +178,24 @@ Drift fails the check, and the step summary lists what was added and removed wit
 
 `scan`'s "completed with warnings" (1) and `check`'s "inconclusive" (3) are the same condition under different numbers; `scan`'s was left alone so existing scripts keep working. Example workflows (pull requests, a weekly schedule, manual dispatch, writing the baseline on the runner) are in [docs/github-action.md](docs/github-action.md).
 
+## Removing SrcLawyer
+
+SrcLawyer writes at most three files into your project, and only when you ask it to:
+
+- `.srclawyer.config.yml`, written by `srclawyer init`.
+- `PRIVACY_POLICY.md`, written by `srclawyer scan` (or the path you give `--out`) unless that file has been edited, in which case [it is left alone](#editing-the-generated-policy).
+- `.srclawyer.inventory.json`, written only when you pass `--write-inventory` to `scan` (or the path you give it).
+
+Delete whichever of them you no longer want. No other SrcLawyer command writes files: `srclawyer check` is read-only, and installing the package writes nothing to your project.
+
+SrcLawyer never creates a workflow file. To stop the [GitHub Action](#drift-check-github-action), delete or edit the workflow you added yourself (for example `.github/workflows/srclawyer.yml`).
+
+To remove the command-line tool:
+
+```bash
+npm uninstall -g srclawyer
+```
+
 ## Network calls
 
 Detection itself is fully local and offline — no code leaves your machine for pattern matching. Once detection completes, every `scan` makes these calls to a SrcLawyer-run service:

package/dist/cli.js

@@ -83,6 +83,7 @@ program
     .option("--no-llm", "skip AI-assisted resolution of ambiguous findings for this run")
     .option("--write-inventory [path]", `also write the drift baseline (data categories and processors only) to <path> (default ${DEFAULT_INVENTORY_PATH}); uses git-aware file discovery in a git repository`)
     .option("--allow-incomplete-inventory", "with --write-inventory: write the baseline even if the scan completed with warnings")
+    .option("--force", "overwrite the policy file even if it was edited since SrcLawyer generated it, or was not generated by SrcLawyer", false)
     .action(async (opts) => {
     await runScan(process.cwd(), {
         json: opts.json,
@@ -90,6 +91,7 @@ program
         llm: opts.llm,
         writeInventory: opts.writeInventory === true ? DEFAULT_INVENTORY_PATH : opts.writeInventory,
         allowIncompleteInventory: opts.allowIncompleteInventory,
+        force: opts.force,
     });
 });
 program

package/dist/commands/init.js

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } 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, byokNetworkNotice } from "../policy/legalNotices.js";
+import { DEFAULT_POLICY_PATH, SUGGESTED_DRAFT_PATH, checkPolicyWrite } from "../policy/policyGuard.js";
 import { runScan } from "./scan.js";
 export const DEFAULT_API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
 const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -177,12 +178,20 @@ export async function runInit(root, flags = {}) {
     console.log(`\nWrote ${CONFIG_FILENAME}. Run "srclawyer scan" to analyze this codebase.`);
     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());
+        // init never overwrites an existing policy. If one is there and scan would refuse to replace it,
+        // don't offer the scan at all; show how to generate a draft next to it instead.
+        const existing = checkPolicyWrite(resolve(root, DEFAULT_POLICY_PATH), DEFAULT_POLICY_PATH, false);
+        if (existing.allowed) {
+            const raw = await ask(lines, "Run a scan now and generate your policy?", "y");
+            runScanNow = /^y(es)?$/i.test(raw.trim());
+        }
+        else {
+            console.log(`\n${DEFAULT_POLICY_PATH} already exists and SrcLawyer will not overwrite it, so no scan was run. To generate a policy to compare against it, run:\n\n  srclawyer scan --out ${SUGGESTED_DRAFT_PATH}`);
+        }
     }
     rl.close();
     if (runScanNow) {
         console.log("");
-        await runScan(root, { json: false, out: "PRIVACY_POLICY.md", llm: true });
+        await runScan(root, { json: false, out: DEFAULT_POLICY_PATH, llm: true });
     }
 }

package/dist/commands/scan.d.ts

@@ -7,5 +7,7 @@ export interface ScanOptions {
     writeInventory?: string;
     /** Write the baseline even if the scan completed with warnings that make it untrustworthy. */
     allowIncompleteInventory?: boolean;
+    /** Overwrite the policy file even if it was edited since SrcLawyer generated it, or was not generated by SrcLawyer. */
+    force?: boolean;
 }
 export declare function runScan(root: string, options: ScanOptions): Promise<void>;

package/dist/commands/scan.js

@@ -4,15 +4,27 @@ import { CONFIG_FILENAME, hasUnmigratedLegacyConfig, legacyConfigMessage, loadCo
 import { scan } from "../engine/scanEngine.js";
 import { formatText } from "../report/formatText.js";
 import { generatePolicyMarkdown } from "../policy/generatePolicy.js";
+import { checkPolicyWrite, withPolicyMarker } from "../policy/policyGuard.js";
 import { resolveProviderForTier } from "../llm/resolveProviderForTier.js";
 import { resolveAmbiguousFindings } from "../llm/resolveAmbiguousFindings.js";
 import { resolveScanProtectedLogic } from "./protectedLogicStep.js";
 import { selectDiscovery } from "../engine/gitDiscovery.js";
 import { computeInventory, inventoryBlockers, serializeInventory } from "../inventory/inventory.js";
+import { EXIT_CRASH } from "../exitCodes.js";
 import { readPackageVersion } from "../version.js";
 import { MAX_FRAGMENT_BYTES } from "../rules/zodPreFilter.js";
 import { SCAN_DISCLAIMER_REMINDER, byokNetworkNotice } from "../policy/legalNotices.js";
 export async function runScan(root, options) {
+    // Refuse before any scanning or network call: a plain scan exists to write this file, so if it is
+    // protected there is nothing useful to do. With --write-inventory the scan still runs, because the
+    // baseline refresh is independent of the policy -- only the policy write is skipped.
+    const policyPath = resolve(root, options.out);
+    let policyDecision = checkPolicyWrite(policyPath, options.out, options.force ?? false);
+    if (!policyDecision.allowed && !options.writeInventory) {
+        console.error(policyDecision.message);
+        process.exitCode = EXIT_CRASH;
+        return;
+    }
     const config = loadConfig(root);
     let legacyConfigWarning = null;
     if (!config) {
@@ -69,8 +81,16 @@ export async function runScan(root, options) {
     }
     const ambiguousCount = findings.filter((f) => f.requiresReview).length;
     const finalResult = { ...result, findings, ambiguousCount };
-    const policyPath = resolve(root, options.out);
-    writeFileSync(policyPath, generatePolicyMarkdown(finalResult, config, llmError, protectedLogicWarning));
+    // Checked again now: a long scan leaves time for the file to be edited since the check above.
+    policyDecision = checkPolicyWrite(policyPath, options.out, options.force ?? false);
+    let policyNote = null;
+    if (policyDecision.allowed) {
+        writeFileSync(policyPath, withPolicyMarker(generatePolicyMarkdown(finalResult, config, llmError, protectedLogicWarning)));
+    }
+    else {
+        policyNote = `Privacy policy not written. ${policyDecision.message}`;
+        console.error(policyNote);
+    }
     let inventoryNote = null;
     if (options.writeInventory && discovery) {
         const blockers = inventoryBlockers(result, protectedLogicWarning);
@@ -90,8 +110,12 @@ export async function runScan(root, options) {
     if (result.unsupportedStackWarning || result.workspaceWarning || result.skippedFilesWarning || llmError || protectedLogicWarning || legacyConfigWarning) {
         process.exitCode = 1;
     }
+    // A refusal is a failure of what a plain scan was asked to do; with --write-inventory the policy
+    // was a side output and skipping it (with the note above) is not.
+    if (policyNote && !options.writeInventory)
+        process.exitCode = EXIT_CRASH;
     if (options.json) {
-        console.log(JSON.stringify({ ...finalResult, policyPath, llmError, protectedLogicWarning, legacyConfigWarning, inventoryNote }, null, 2));
+        console.log(JSON.stringify({ ...finalResult, policyPath, policyWritten: policyNote === null, policySkippedReason: policyNote, llmError, protectedLogicWarning, legacyConfigWarning, inventoryNote }, null, 2));
         return;
     }
     console.log(formatText(finalResult, { aiReviewEnabled: config?.tier === "byok" }));
@@ -99,6 +123,6 @@ export async function runScan(root, options) {
         console.log(`\n${protectedLogicWarning}`);
     if (legacyConfigWarning)
         console.log(`\n${legacyConfigWarning}`);
-    console.log(`\nPrivacy policy written to ${join(options.out)}`);
+    console.log(policyNote ? "\nPrivacy policy not written (see above)." : `\nPrivacy policy written to ${join(options.out)}`);
     console.log(`\n${SCAN_DISCLAIMER_REMINDER}`);
 }

package/dist/policy/policyGuard.d.ts

@@ -0,0 +1,20 @@
+/** Where `scan` writes the policy unless told otherwise. */
+export declare const DEFAULT_POLICY_PATH = "PRIVACY_POLICY.md";
+/** The path suggested for a side-by-side draft when the real policy is protected. */
+export declare const SUGGESTED_DRAFT_PATH = "PRIVACY_POLICY.generated.md";
+/** Appends the marker line to a freshly generated policy. */
+export declare function withPolicyMarker(body: string): string;
+export type PolicyFileState = "missing" | "unchanged" | "edited" | "unmarked";
+/** What an existing file at `path` is, relative to what SrcLawyer last generated. */
+export declare function classifyPolicyFile(path: string): PolicyFileState;
+export type PolicyWriteDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    kind: "edited" | "unmarked";
+    message: string;
+};
+export declare function editedMessage(path: string): string;
+export declare function unmarkedMessage(path: string): string;
+/** Whether `scan` may write its policy to `path`. `displayPath` is the path as the user gave it. */
+export declare function checkPolicyWrite(path: string, displayPath: string, force: boolean): PolicyWriteDecision;

package/dist/policy/policyGuard.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+// Overwrite protection for the generated privacy policy. Every policy SrcLawyer writes ends with a
+// marker line holding a SHA-256 of the rest of the file. Before writing over an existing file we
+// recompute that hash: a match means nobody has touched it since we generated it (safe to
+// regenerate); anything else means it is someone's work and is left alone unless --force is passed.
+// This detects changes, it is not a security feature -- anyone can recompute the hash.
+const MARKER_PREFIX = "<!-- srclawyer:policy-sha256=";
+const MARKER_LINE = /^<!-- srclawyer:policy-sha256=([0-9a-f]{64}) -->$/;
+/** Where `scan` writes the policy unless told otherwise. */
+export const DEFAULT_POLICY_PATH = "PRIVACY_POLICY.md";
+/** The path suggested for a side-by-side draft when the real policy is protected. */
+export const SUGGESTED_DRAFT_PATH = "PRIVACY_POLICY.generated.md";
+// CRLF/CR become LF and trailing whitespace is dropped, so a Windows checkout (autocrlf) or an editor
+// that adds or strips the final newline is not mistaken for a hand edit.
+function normalize(text) {
+    return text.replace(/\r\n?/g, "\n").trimEnd();
+}
+function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/** Appends the marker line to a freshly generated policy. */
+export function withPolicyMarker(body) {
+    const terminated = body.endsWith("\n") ? body : `${body}\n`;
+    return `${terminated}${MARKER_PREFIX}${sha256(normalize(body))} -->\n`;
+}
+/** What an existing file at `path` is, relative to what SrcLawyer last generated. */
+export function classifyPolicyFile(path) {
+    if (!existsSync(path))
+        return "missing";
+    const lines = readFileSync(path, "utf8").replace(/\r\n?/g, "\n").split("\n");
+    let markerIndex = -1;
+    let recorded = "";
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const match = MARKER_LINE.exec(lines[i].trim());
+        if (match) {
+            markerIndex = i;
+            recorded = match[1];
+            break;
+        }
+    }
+    if (markerIndex === -1)
+        return "unmarked";
+    // Everything except the marker line counts, including text added after it.
+    const rest = lines.filter((_, i) => i !== markerIndex).join("\n");
+    return sha256(normalize(rest)) === recorded ? "unchanged" : "edited";
+}
+function alternativeOut(path) {
+    return path === SUGGESTED_DRAFT_PATH ? "a different path" : SUGGESTED_DRAFT_PATH;
+}
+export function editedMessage(path) {
+    return `Not overwriting ${path}: it has been edited since SrcLawyer generated it. Write the new policy to a separate file with --out ${alternativeOut(path)} and compare, or pass --force to replace it.`;
+}
+export function unmarkedMessage(path) {
+    return `Not overwriting ${path}: it was not generated by this version of SrcLawyer (it may be hand-written, or generated before overwrite protection was added in 0.8.0). Write the new policy to a separate file with --out ${alternativeOut(path)} and compare, or pass --force to replace it.`;
+}
+/** Whether `scan` may write its policy to `path`. `displayPath` is the path as the user gave it. */
+export function checkPolicyWrite(path, displayPath, force) {
+    if (force)
+        return { allowed: true };
+    // A directory is not a policy file; let the write fail the way it always has.
+    if (existsSync(path) && statSync(path).isDirectory())
+        return { allowed: true };
+    const state = classifyPolicyFile(path);
+    if (state === "edited")
+        return { allowed: false, kind: "edited", message: editedMessage(displayPath) };
+    if (state === "unmarked")
+        return { allowed: false, kind: "unmarked", message: unmarkedMessage(displayPath) };
+    return { allowed: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "srclawyer",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Static analysis engine that derives privacy policy documentation directly from source code",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",