srclawyer 0.4.0 → 0.5.0

package/README.md

@@ -8,16 +8,58 @@ Static analysis engine that derives privacy policy documentation directly from s
 
 ## Usage
 
+No install needed for a first try — `npx` fetches and runs the latest version on demand:
+
+```bash
+npx srclawyer init     # one-time: jurisdiction, markets, industry
+npx srclawyer scan     # analyze the codebase and write PRIVACY_POLICY.md
+```
+
+For a persistent `srclawyer` command instead of typing `npx` every time:
+
 ```bash
+npm install -g srclawyer
+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
+```
+
+If `srclawyer` isn't found right after a global install, see [Troubleshooting: command not found](#troubleshooting-command-not-found) below.
+
+## Development
+
+Working on SrcLawyer itself (not just using it):
+
+```bash
+git clone https://github.com/SrcLawyer/srclawyer.git
+cd srclawyer
 npm install
 npm run build
-node dist/cli.js init            # one-time: jurisdiction, markets, industry
-node dist/cli.js scan            # analyze the codebase and write PRIVACY_POLICY.md
-node dist/cli.js scan --json     # findings as JSON (still writes the policy file)
-node dist/cli.js scan --out docs/privacy.md
+node dist/cli.js scan
 ```
 
-During development, run directly from source with `npm run dev -- scan`.
+Or run directly from source without building first: `npm run dev -- scan`.
+
+## Troubleshooting: command not found
+
+After `npm install -g srclawyer`, the install prints `added N packages` but the `srclawyer` command isn't recognized. This almost always means the command *was* installed — npm's own global bin directory just isn't on your shell's `PATH`, or your shell doesn't know about it yet.
+
+**The most common cause: conda.** If you have Anaconda/Miniconda installed with `auto_activate_base` enabled (the default), conda prepends its own directories to `PATH` every time a new shell starts — this can land ahead of, or instead of, the directory npm actually installed into. Symptoms: `srclawyer` works in some terminals/tabs but not others, or never works despite the install reporting success.
+
+Steps, in order of how likely each is to fix it:
+
+1. **Open a brand-new terminal window or tab.** `PATH` is set when a shell starts; a terminal that was already open won't pick up a global install that happened after it launched.
+2. **If a new terminal doesn't help, check where npm actually put it versus what's on your `PATH`:**
+   ```bash
+   npm config get prefix      # where npm installs global packages
+   echo $PATH                 # does the above, plus "/bin", appear in here?
+   ```
+   If `npm config get prefix`'s `bin` subdirectory (or, on Windows, the prefix itself) isn't listed in `$PATH` at all, that's the root cause — your shell's startup files (`.zshrc`, `.bashrc`, `.bash_profile`) need a line adding it, e.g. `export PATH="$(npm config get prefix)/bin:$PATH"`.
+3. **If conda specifically is the culprit** (its paths appear in `$PATH` ahead of npm's prefix, or npm's prefix is missing because conda's own Node/npm shadowed the one you expected to use): either run `conda deactivate` before using `srclawyer`, or turn off automatic activation so it stops happening on every new shell: `conda config --set auto_activate_base false`.
+4. **If `srclawyer` still isn't found after fixing `PATH`**, your shell may have cached the old (missing) command location. Clear that cache: `hash -r` (bash) or `rehash` (zsh), then try again without opening a new terminal.
+
+If none of this resolves it, `npx srclawyer scan` (see [Usage](#usage) above) sidesteps `PATH` entirely, since `npx` always invokes the binary directly rather than relying on it being a recognized shell command.
 
 ## What `scan` does today
 

package/dist/commands/init.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { CONFIG_FILENAME, DEFAULT_CONFIG, configPath, writeConfig } from "../config/config.js";
+import { CONFIG_FILENAME, DEFAULT_CONFIG, configPath, hasUnmigratedLegacyConfig, legacyConfigMessage, writeConfig, } from "../config/config.js";
 function guessIndustry(root) {
     const pkgPath = join(root, "package.json");
     if (!existsSync(pkgPath))
@@ -29,6 +29,10 @@ export async function runInit(root) {
         console.log(`${CONFIG_FILENAME} already exists. Delete it first if you want to redo setup.`);
         return;
     }
+    if (hasUnmigratedLegacyConfig(root)) {
+        console.log(legacyConfigMessage());
+        return;
+    }
     const guessedIndustry = guessIndustry(root);
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const lines = rl[Symbol.asyncIterator]();

package/dist/commands/scan.js

@@ -1,6 +1,6 @@
 import { writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { loadConfig } from "../config/config.js";
+import { CONFIG_FILENAME, hasUnmigratedLegacyConfig, legacyConfigMessage, loadConfig } from "../config/config.js";
 import { scan } from "../engine/scanEngine.js";
 import { formatText } from "../report/formatText.js";
 import { generatePolicyMarkdown } from "../policy/generatePolicy.js";
@@ -10,8 +10,15 @@ import { resolveProtectedLogic } from "../cloud/resolveProtectedLogic.js";
 import { resolveProtectedLogicEndpoint } from "../cloud/config.js";
 export async function runScan(root, options) {
     const config = loadConfig(root);
+    let legacyConfigWarning = null;
     if (!config) {
-        console.error('No .privacypolicy.yml found. Run "srclawyer init" first.\n');
+        if (hasUnmigratedLegacyConfig(root)) {
+            legacyConfigWarning = legacyConfigMessage();
+            console.error(legacyConfigWarning);
+        }
+        else {
+            console.error(`No ${CONFIG_FILENAME} found. Run "srclawyer init" first.\n`);
+        }
     }
     const result = await scan(root);
     let findings = result.findings;
@@ -52,11 +59,11 @@ export async function runScan(root, options) {
     const finalResult = { ...result, findings, ambiguousCount };
     const policyPath = resolve(root, options.out);
     writeFileSync(policyPath, generatePolicyMarkdown(finalResult, config, llmError));
-    if (result.unsupportedStackWarning || llmError || protectedLogicWarning) {
+    if (result.unsupportedStackWarning || llmError || protectedLogicWarning || legacyConfigWarning) {
         process.exitCode = 1;
     }
     if (options.json) {
-        console.log(JSON.stringify({ ...finalResult, policyPath, llmError, protectedLogicWarning }, null, 2));
+        console.log(JSON.stringify({ ...finalResult, policyPath, llmError, protectedLogicWarning, legacyConfigWarning }, null, 2));
         return;
     }
     console.log(formatText(finalResult));

package/dist/config/config.d.ts

@@ -1,4 +1,6 @@
-export declare const CONFIG_FILENAME = ".privacypolicy.yml";
+export declare const CONFIG_FILENAME = ".srclawyer.config.yml";
+/** The pre-0.5.0 name. Never auto-migrated or silently read as a fallback -- see legacyConfigMessage. */
+export declare const LEGACY_CONFIG_FILENAME = ".privacypolicy.yml";
 export type SrcLawyerTier = "free" | "byok" | "managed";
 export interface SrcLawyerLlmConfig {
     provider: "anthropic";
@@ -14,5 +16,15 @@ export interface SrcLawyerConfig {
 }
 export declare const DEFAULT_CONFIG: SrcLawyerConfig;
 export declare function configPath(root: string): string;
+export declare function legacyConfigPath(root: string): string;
+/** True only when the old file is present and the new one isn't -- never fires once migrated. */
+export declare function hasUnmigratedLegacyConfig(root: string): boolean;
+/**
+ * Single source of truth for this message so init and scan can't drift into saying it two different
+ * ways. Deliberately never auto-reads the legacy file as a fallback, even though the YAML shape is
+ * identical -- the rename needs to be an explicit, visible action, not a silent compatibility shim
+ * that lets the old filename linger indefinitely.
+ */
+export declare function legacyConfigMessage(): string;
 export declare function loadConfig(root: string): SrcLawyerConfig | null;
 export declare function writeConfig(root: string, config: SrcLawyerConfig): void;

package/dist/config/config.js

@@ -1,7 +1,9 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import yaml from "js-yaml";
-export const CONFIG_FILENAME = ".privacypolicy.yml";
+export const CONFIG_FILENAME = ".srclawyer.config.yml";
+/** The pre-0.5.0 name. Never auto-migrated or silently read as a fallback -- see legacyConfigMessage. */
+export const LEGACY_CONFIG_FILENAME = ".privacypolicy.yml";
 export const DEFAULT_CONFIG = {
     entityLocation: null,
     targetMarkets: [],
@@ -12,6 +14,22 @@ export const DEFAULT_CONFIG = {
 export function configPath(root) {
     return join(root, CONFIG_FILENAME);
 }
+export function legacyConfigPath(root) {
+    return join(root, LEGACY_CONFIG_FILENAME);
+}
+/** True only when the old file is present and the new one isn't -- never fires once migrated. */
+export function hasUnmigratedLegacyConfig(root) {
+    return existsSync(legacyConfigPath(root)) && !existsSync(configPath(root));
+}
+/**
+ * Single source of truth for this message so init and scan can't drift into saying it two different
+ * ways. Deliberately never auto-reads the legacy file as a fallback, even though the YAML shape is
+ * identical -- the rename needs to be an explicit, visible action, not a silent compatibility shim
+ * that lets the old filename linger indefinitely.
+ */
+export function legacyConfigMessage() {
+    return `Found a legacy ${LEGACY_CONFIG_FILENAME} from an older version of SrcLawyer. Rename it to keep your existing settings:\n\n  mv ${LEGACY_CONFIG_FILENAME} ${CONFIG_FILENAME}\n\nThen re-run this command. (If you'd rather start fresh instead, delete ${LEGACY_CONFIG_FILENAME} first.)`;
+}
 export function loadConfig(root) {
     const path = configPath(root);
     if (!existsSync(path))

package/dist/llm/resolveProviderForTier.d.ts

@@ -1,3 +1,3 @@
-import type { SrcLawyerConfig } from "../config/config.js";
+import { type SrcLawyerConfig } from "../config/config.js";
 import type { ProviderResolution } from "./types.js";
 export declare function resolveProviderForTier(config: SrcLawyerConfig): ProviderResolution;

package/dist/llm/resolveProviderForTier.js

@@ -1,3 +1,4 @@
+import { CONFIG_FILENAME } from "../config/config.js";
 import { AnthropicProvider } from "./anthropicProvider.js";
 export function resolveProviderForTier(config) {
     const tier = config.tier ?? "free";
@@ -9,7 +10,7 @@ export function resolveProviderForTier(config) {
         if (!envVar) {
             return {
                 provider: null,
-                error: 'Tier is "byok" but no API key environment variable is configured in .privacypolicy.yml. Run "srclawyer init" to set one.',
+                error: `Tier is "byok" but no API key environment variable is configured in ${CONFIG_FILENAME}. Run "srclawyer init" to set one.`,
             };
         }
         const apiKey = process.env[envVar];
@@ -27,5 +28,5 @@ export function resolveProviderForTier(config) {
             error: 'Tier is "managed" but SrcLawyer\'s managed backend is not available yet. Use "byok" with your own Anthropic API key, or "free".',
         };
     }
-    return { provider: null, error: `Unknown tier "${tier}" in .privacypolicy.yml.` };
+    return { provider: null, error: `Unknown tier "${tier}" in ${CONFIG_FILENAME}.` };
 }

package/dist/policy/generatePolicy.d.ts

@@ -1,3 +1,3 @@
 import type { ScanResult } from "../engine/types.js";
-import type { SrcLawyerConfig } from "../config/config.js";
+import { type SrcLawyerConfig } from "../config/config.js";
 export declare function generatePolicyMarkdown(result: ScanResult, config: SrcLawyerConfig | null, llmError?: string | null): string;

package/dist/policy/generatePolicy.js

@@ -1,3 +1,4 @@
+import { CONFIG_FILENAME } from "../config/config.js";
 import { DATA_CATEGORY_LABELS } from "./dataCategoryLabels.js";
 import { MANDATORY_DISCLAIMER } from "./disclaimer.js";
 function locationRef(finding) {
@@ -88,7 +89,7 @@ function renderContextSection(config) {
         return [
             "## Scope",
             "",
-            "No `.privacypolicy.yml` configuration was found, so this policy was generated without jurisdiction, target-market, or industry context. Run `srclawyer init` and re-run `srclawyer scan` to include that context.",
+            `No \`${CONFIG_FILENAME}\` configuration was found, so this policy was generated without jurisdiction, target-market, or industry context. Run \`srclawyer init\` and re-run \`srclawyer scan\` to include that context.`,
         ].join("\n");
     }
     const lines = ["## Scope", ""];
@@ -129,6 +130,9 @@ export function generatePolicyMarkdown(result, config, llmError) {
     if (categorySections.length > 0) {
         parts.push(categorySections.join("\n\n"));
     }
+    else if (result.unsupportedStackWarning) {
+        parts.push("**Not analyzed:** this codebase's primary language/framework isn't supported yet (see the warning above). This is not a clean-scan result — nothing below should be read as \"no data collection found.\"");
+    }
     else {
         parts.push("No data-collection patterns were confidently identified in this codebase.");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "srclawyer",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Static analysis engine that derives privacy policy documentation directly from source code",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -20,11 +20,13 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "postinstall.cjs"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepare": "npm run build",
+    "postinstall": "node postinstall.cjs",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "test:corpus": "tsx scripts/scoreCorpus.ts",

package/postinstall.cjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Advisory-only PATH check, run via the "postinstall" lifecycle hook. Plain, dependency-free
+ * CommonJS (not compiled from src/) on purpose: postinstall fires BEFORE "prepare" in npm's
+ * lifecycle order, so dist/ doesn't exist yet during this repo's own `npm install` -- a compiled
+ * script referencing dist/ would break every contributor's first install. A real, pre-built
+ * tarball install (the actual target of this check) always has this file on disk already.
+ *
+ * IMPORTANT, confirmed empirically: npm (v7+) does NOT share stdio with lifecycle scripts by
+ * default -- normal process.stdout/stderr writes from here are silently swallowed for a plain
+ * `npm install -g`, visible only with the rarely-used --foreground-scripts flag. Exiting non-zero
+ * to force visibility was tried and rejected -- it doesn't just print an ugly error, it makes npm
+ * abort the install entirely (the package's files never get placed), which is worse than saying
+ * nothing. Writing directly to the controlling terminal device (bypassing the suppressed stdio) is
+ * the standard real-world workaround for this exact npm behavior, so that's what this does, with a
+ * plain stderr write as the fallback for when there's no TTY to open (CI, non-interactive installs)
+ * -- at that point this is genuinely best-effort, not guaranteed.
+ *
+ * Never fails the install over this: worst case is silence, never a non-zero exit or a thrown
+ * error reaching npm's own install process.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+function pathImplFor(platform) {
+  return platform === "win32" ? path.win32 : path.posix;
+}
+
+function globalBinDir(prefix, platform) {
+  if (!prefix) return null;
+  return platform === "win32" ? prefix : pathImplFor(platform).join(prefix, "bin");
+}
+
+function normalize(p, platform) {
+  let resolved = pathImplFor(platform).resolve(p).replace(/[\\/]+$/, "");
+  if (platform === "win32" || platform === "darwin") resolved = resolved.toLowerCase();
+  return resolved;
+}
+
+/** Pure, testable: is `dir` present among `pathEnv`'s entries, resolved and normalized? */
+function isDirOnPath(dir, pathEnv, platform) {
+  if (!dir) return true; // can't determine the target dir -- don't false-positive a warning
+  const target = normalize(dir, platform);
+  const delimiter = platform === "win32" ? ";" : ":";
+  const entries = (pathEnv || "").split(delimiter).filter(Boolean);
+  return entries.some((entry) => normalize(entry, platform) === target);
+}
+
+function printWarning(message) {
+  // npm doesn't share stdio with lifecycle scripts by default -- a plain stderr write here is
+  // silently swallowed for a normal `npm install -g`. Writing straight to the controlling terminal
+  // bypasses that. Falls back to stderr (visible with --foreground-scripts, or if something else
+  // in the chain does share stdio) when there's no TTY to open -- CI, piped/non-interactive installs.
+  try {
+    const ttyPath = process.platform === "win32" ? "\\\\.\\CON" : "/dev/tty";
+    const fd = fs.openSync(ttyPath, "w");
+    try {
+      fs.writeSync(fd, message);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    try {
+      process.stderr.write(message);
+    } catch {
+      // Truly nothing we can do -- advisory only, never throw from here.
+    }
+  }
+}
+
+function main() {
+  try {
+    if (process.env.npm_config_global !== "true") return; // local/dependency install, or npx -- not our concern
+
+    const bin = globalBinDir(process.env.npm_config_prefix, process.platform);
+    if (isDirOnPath(bin, process.env.PATH, process.platform)) return;
+
+    printWarning(
+      [
+        "",
+        '⚠ srclawyer installed, but the "srclawyer" command isn’t on your PATH yet.',
+        "  This is often caused by tools like conda (auto_activate_base) rearranging PATH ahead of",
+        "  npm's global bin directory. Try opening a new terminal window first.",
+        "  If that doesn't fix it, see the Troubleshooting section in the README:",
+        "  https://github.com/SrcLawyer/srclawyer#troubleshooting-command-not-found",
+        "",
+      ].join("\n")
+    );
+  } catch {
+    // Advisory only -- never let this check itself break an install.
+  }
+}
+
+main();
+
+module.exports = { isDirOnPath, globalBinDir, normalize };