@sous-io/sous 0.1.0

package/src/lib/build-service.ts

@@ -0,0 +1,258 @@
+import path from "node:path";
+import fs from "node:fs";
+import type { ConfigContext, Settings } from "./settings.js";
+import { resolveProjectCompilation, resolveRootScope, resolveScope } from "./settings.js";
+import { resolveIncludeCandidates } from "./include-resolver.js";
+import { CompilationService } from "./markdown-compiler.js";
+import type { CompilationConfig, CompilationTarget } from "./markdown-compiler.js";
+import { StateService } from "./state.js";
+import { log } from "../utils/formatting.js";
+
+export type BuildOptions = {
+  strict?: boolean;
+  rebuild?: boolean;
+  dryRun?: boolean;
+  noCompile?: boolean;
+  noPrune?: boolean;
+  /**
+   * When set, only targets that transitively include this file are compiled.
+   * All other targets are skipped. If no targets include this file, compilation
+   * is skipped entirely.
+   */
+  changedFile?: string;
+  /**
+   * Where the active config was discovered. Threaded into variable resolution so
+   * `${sousDir}` resolves and so state/PID paths default into `.sous/`.
+   */
+  configContext?: ConfigContext;
+};
+
+/**
+ * Recursively collects all file paths reachable from `filePath` via @include chains.
+ * Returns a Set of absolute paths. The `visited` set prevents infinite loops.
+ *
+ * Matches the same @<path>.md include lines as CompilationService.processIncludes,
+ * including alias/`${var}` paths, resolving each via the same candidate logic
+ * (first existing wins).
+ */
+function collectIncludeGraph(
+  filePath: string,
+  resolveOpts: { aliases?: Record<string, string[]>; scope?: Record<string, string> } = {},
+  visited: Set<string> = new Set()
+): Set<string> {
+  if (visited.has(filePath)) return visited;
+  visited.add(filePath);
+
+  if (!fs.existsSync(filePath)) return visited;
+
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, "utf8");
+  } catch {
+    return visited;
+  }
+
+  const includePattern = /^@([~a-zA-Z0-9_${}][a-zA-Z0-9_\-/.:${}]*\.md)$/gm;
+  const baseDir = path.dirname(filePath);
+  let match: RegExpExecArray | null;
+
+  while ((match = includePattern.exec(content)) !== null) {
+    const includePath = match[1].trim();
+    const candidates = resolveIncludeCandidates(includePath, {
+      aliases: resolveOpts.aliases,
+      scope: resolveOpts.scope,
+      baseDir,
+    });
+    const fullPath = candidates.find((c) => fs.existsSync(c)) ?? candidates[0];
+    collectIncludeGraph(fullPath, resolveOpts, visited);
+  }
+
+  return visited;
+}
+
+/**
+ * Returns the subset of compilation targets that transitively include `filePath`.
+ * A target is affected if its `rootInputPath` equals `filePath`, or if `filePath`
+ * is reachable via @include chains from `rootInputPath`.
+ *
+ * Uses a simple recursive file scan — reads each .md file and checks for
+ * @<path> include lines. Does not compile; just walks the include graph.
+ */
+export function findAffectedTargets(
+  filePath: string,
+  config: CompilationConfig
+): CompilationTarget[] {
+  return config.targets.filter(target => {
+    const graph = collectIncludeGraph(target.rootInputPath, {
+      aliases: config.aliases,
+      scope: config.includeScope,
+    });
+    return graph.has(filePath);
+  });
+}
+
+/**
+ * Resolves the state file path for a project.
+ *
+ * The path is derived from the PROJECT scope (root vars → project `_vars`), so a
+ * `stateFilePath` or `sousDir` defined at either level is honoured. Resolving
+ * from the root scope alone was a bug: project-level values were ignored and
+ * state silently landed in cwd.
+ *
+ * @param projectKey - The project's key in `settings.projects`.
+ * @param settings - The loaded root settings.
+ * @param configContext - Where the config was discovered (supplies `sousDir`).
+ * @returns Absolute path to the project's state file.
+ */
+export function resolveStateFilePath(
+  projectKey: string,
+  settings: Settings,
+  configContext?: ConfigContext
+): string {
+  const rootScope = resolveRootScope(settings, configContext);
+  const project = settings.projects[projectKey];
+  const projectScope = resolveScope(project?._vars ?? {}, rootScope);
+  const projectCount = Object.keys(settings.projects ?? {}).length;
+  return new StateService().getFilePath(projectKey, projectScope, projectCount);
+}
+
+export class BuildService {
+  /**
+   * Runs compile + prune for a project.
+   * Returns true if all steps succeeded.
+   */
+  async build(
+    projectKey: string,
+    settings: Settings,
+    options: BuildOptions = {}
+  ): Promise<boolean> {
+    const rootScope = resolveRootScope(settings, options.configContext);
+    const project = settings.projects[projectKey];
+
+    if (!project) {
+      throw new Error(`Project '${projectKey}' not found in settings`);
+    }
+
+    const stateService = new StateService();
+    const stateFilePath = resolveStateFilePath(projectKey, settings, options.configContext);
+
+    let success = true;
+
+    // When --rebuild, clear all previously written files before compiling so that
+    // orphaned outputs (files no longer produced by the current config) are removed.
+    // Prune cannot catch these because compile overwrites the state file before prune runs.
+    if (options.rebuild && !options.dryRun && !options.noCompile) {
+      const existingState = await stateService.load(stateFilePath);
+      if (existingState?.files.length) {
+        stateService.deleteTrackedFiles(existingState.files, existingState.dirs);
+      }
+    }
+
+    // Compile step
+    if (!options.noCompile) {
+      const config = resolveProjectCompilation(project, rootScope, settings, projectKey);
+      if (config) {
+        let effectiveConfig: CompilationConfig = config;
+
+        if (options.changedFile) {
+          const affectedTargets = findAffectedTargets(options.changedFile, config);
+          if (affectedTargets.length === 0) {
+            log(`  ⊘ No targets affected by change to ${options.changedFile} — skipping compilation`);
+          } else {
+            effectiveConfig = { ...config, targets: affectedTargets };
+            const compiler = new CompilationService({
+              strict: options.strict,
+              rebuild: options.rebuild,
+              dryRun: options.dryRun,
+            });
+            const compileOk = await compiler.compile(effectiveConfig, stateFilePath);
+            if (!compileOk) success = false;
+          }
+        } else {
+          const compiler = new CompilationService({
+            strict: options.strict,
+            rebuild: options.rebuild,
+            dryRun: options.dryRun,
+          });
+          const compileOk = await compiler.compile(effectiveConfig, stateFilePath);
+          if (!compileOk) success = false;
+        }
+      }
+    }
+
+    // Prune step
+    if (!options.noPrune && success) {
+      await this.prune(
+        projectKey,
+        settings,
+        stateFilePath,
+        options.dryRun,
+        options.configContext
+      );
+    }
+
+    return success;
+  }
+
+  /**
+   * Removes output files that are tracked in state but no longer in the current config.
+   * Also removes Sous-created directories that are now empty.
+   */
+  async prune(
+    projectKey: string,
+    settings: Settings,
+    stateFilePath: string,
+    dryRun = false,
+    configContext?: ConfigContext
+  ): Promise<void> {
+    const stateService = new StateService();
+    const state = await stateService.load(stateFilePath);
+    if (!state || state.files.length === 0) return;
+
+    const rootScope = resolveRootScope(settings, configContext);
+    const project = settings.projects[projectKey];
+    const config = project
+      ? resolveProjectCompilation(project, rootScope, settings, projectKey)
+      : null;
+
+    // Collect the current output set: explicit files and active destinationDir prefixes
+    const currentOutputFiles = new Set<string>();
+    const currentOutputDirs = new Set<string>();
+    if (config) {
+      for (const target of config.targets) {
+        for (const output of target.outputs) {
+          if (output.destinationFile) currentOutputFiles.add(output.destinationFile);
+          if (output.destinationDir) currentOutputDirs.add(output.destinationDir);
+        }
+      }
+    }
+
+    // A state entry is current if it matches an explicit destinationFile, or if its dest
+    // path falls under an active destinationDir (glob target output).
+    function isCurrentOutput(dest: string): boolean {
+      if (currentOutputFiles.has(dest)) return true;
+      for (const dir of currentOutputDirs) {
+        if (dest.startsWith(dir + path.sep) || dest.startsWith(dir + "/")) return true;
+      }
+      return false;
+    }
+
+    // Find files to prune
+    const toDelete = state.files.filter(f => !isCurrentOutput(f.dest));
+
+    if (dryRun) {
+      for (const entry of toDelete) {
+        console.log(`  ○ would prune: ${entry.dest}`);
+      }
+      return;
+    }
+
+    stateService.deleteTrackedFiles(toDelete, state.dirs);
+    for (const entry of toDelete) console.log(`  ✗ pruned: ${entry.dest}`);
+
+    // Update state: remove pruned entries and any dirs that no longer exist
+    state.files = state.files.filter(f => isCurrentOutput(f.dest));
+    state.dirs = state.dirs.filter(d => fs.existsSync(d));
+    await stateService.save(stateFilePath, state);
+  }
+}

package/src/lib/config-discovery.ts

@@ -0,0 +1,199 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * The directory name sous looks for when walking up from the working directory.
+ */
+export const SOUS_DIR_NAME = ".sous";
+
+/**
+ * Config file names searched inside a `.sous/` directory, in priority order.
+ * The first one that exists wins.
+ */
+export const CONFIG_FILE_NAMES = [
+  "sous.config.js",
+  "sous.config.mjs",
+  "sous.config.json",
+] as const;
+
+/**
+ * The name of the optional shared-defaults env file inside `.sous/`. This file
+ * is meant to be committed: it holds values a whole team shares, never secrets.
+ */
+export const ENV_DEFAULTS_NAME = ".env";
+
+/** The name of the optional machine-specific env file inside `.sous/`. */
+export const ENV_LOCAL_NAME = ".env.local";
+
+/** A located sous configuration. */
+export type DiscoveredConfig = {
+  /** Absolute path to the config file itself. */
+  configPath: string;
+  /**
+   * Absolute path to the `.sous/` directory holding the config, when the config
+   * was found by walking up. For an explicit `--config` path this is the config
+   * file's parent directory, whatever it is called.
+   */
+  sousDir: string;
+  /** How the config was located. */
+  source: "flag" | "walk-up";
+};
+
+/**
+ * Returns the list of directories to check, starting at `startDir` and walking
+ * up to the filesystem root. Used by discovery and by the not-found error message.
+ */
+export function candidateDirs(startDir: string): string[] {
+  const dirs: string[] = [];
+  let current = path.resolve(startDir);
+
+  for (;;) {
+    dirs.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return dirs;
+}
+
+/**
+ * Returns the first config file that exists inside `sousDir`, or null.
+ */
+export function findConfigInSousDir(sousDir: string): string | null {
+  for (const name of CONFIG_FILE_NAMES) {
+    const candidate = path.join(sousDir, name);
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Walks up from `startDir` looking for a `.sous/` directory that contains one of
+ * CONFIG_FILE_NAMES. The first directory with a match wins; a `.sous/` directory
+ * without a config file does not stop the walk.
+ *
+ * @param startDir - Directory to start from (normally `process.cwd()`).
+ * @returns The discovered config, or null when nothing was found.
+ */
+export function discoverConfig(startDir: string = process.cwd()): DiscoveredConfig | null {
+  for (const dir of candidateDirs(startDir)) {
+    const sousDir = path.join(dir, SOUS_DIR_NAME);
+    if (!fs.existsSync(sousDir) || !fs.statSync(sousDir).isDirectory()) continue;
+
+    const configPath = findConfigInSousDir(sousDir);
+    if (configPath) return { configPath, sousDir, source: "walk-up" };
+  }
+
+  return null;
+}
+
+/**
+ * Resolves an explicit `--config` value into a DiscoveredConfig.
+ *
+ * The value may point at a config file or at a directory. A directory is searched
+ * for CONFIG_FILE_NAMES, and if the directory itself is not named `.sous`, its
+ * `.sous/` child is searched too — so `--config .` works inside a project root.
+ *
+ * @param configFlag - The raw `--config` value (relative paths resolve against cwd).
+ * @param cwd - Base directory for relative paths.
+ * @returns The resolved config.
+ * @throws When the path does not exist or holds no recognised config file.
+ */
+export function resolveConfigFlag(
+  configFlag: string,
+  cwd: string = process.cwd()
+): DiscoveredConfig {
+  const resolved = path.resolve(cwd, expandHome(configFlag));
+
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`--config path not found: ${resolved}`);
+  }
+
+  if (fs.statSync(resolved).isDirectory()) {
+    const direct = findConfigInSousDir(resolved);
+    if (direct) {
+      return { configPath: direct, sousDir: resolved, source: "flag" };
+    }
+
+    const nested = path.join(resolved, SOUS_DIR_NAME);
+    if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
+      const nestedConfig = findConfigInSousDir(nested);
+      if (nestedConfig) {
+        return { configPath: nestedConfig, sousDir: nested, source: "flag" };
+      }
+    }
+
+    throw new Error(
+      `--config points at a directory with no sous config file: ${resolved}\n` +
+        `Looked for: ${CONFIG_FILE_NAMES.join(", ")}`
+    );
+  }
+
+  return { configPath: resolved, sousDir: path.dirname(resolved), source: "flag" };
+}
+
+/**
+ * Expands a leading `~` to the user's home directory. Leaves other paths alone.
+ */
+export function expandHome(inputPath: string): string {
+  if (inputPath === "~") return process.env.HOME ?? inputPath;
+  if (inputPath.startsWith("~/")) {
+    const home = process.env.HOME;
+    if (home) return path.join(home, inputPath.slice(2));
+  }
+  return inputPath;
+}
+
+/**
+ * Builds the message shown when no config could be found. Names every directory
+ * that was checked and shows how to fix it.
+ *
+ * @param startDir - The directory discovery started from.
+ */
+export function formatNotFoundMessage(startDir: string = process.cwd()): string {
+  const dirs = candidateDirs(startDir);
+  const shown = dirs.slice(0, 8);
+  const omitted = dirs.length - shown.length;
+
+  const checked = shown
+    .map((dir) => `    ${path.join(dir, SOUS_DIR_NAME)}/`)
+    .join("\n");
+
+  const more = omitted > 0 ? `\n    ... and ${omitted} more parent director${omitted === 1 ? "y" : "ies"}` : "";
+
+  return [
+    "No sous config found.",
+    "",
+    `Starting at ${startDir}, sous walked up looking for a ${SOUS_DIR_NAME}/ directory`,
+    `containing one of: ${CONFIG_FILE_NAMES.join(", ")}`,
+    "",
+    "  Checked:",
+    checked + more,
+    "",
+    "  To fix this, either:",
+    `    1. Create ${SOUS_DIR_NAME}/${CONFIG_FILE_NAMES[0]} in your project root, or`,
+    "    2. Pass the config explicitly: xcv <command> --config <path>",
+    "",
+    `  A minimal ${CONFIG_FILE_NAMES[0]}:`,
+    "",
+    "    export const config = {",
+    '      defaultProject: "myproject",',
+    "      projects: {",
+    "        myproject: {",
+    '          name: "My Project",',
+    "          compilation: {",
+    "            targets: [",
+    "              {",
+    '                entryPoint: "${sousDir}/AGENTS.md",',
+    '                outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],',
+    "              },",
+    "            ],",
+    "          },",
+    "        },",
+    "      },",
+    "    };",
+  ].join("\n");
+}

package/src/lib/env-local.ts

@@ -0,0 +1,195 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ENV_DEFAULTS_NAME, ENV_LOCAL_NAME } from "./config-discovery.js";
+
+/**
+ * Parses `.env` / `.env.local` style content into a flat key/value map.
+ *
+ * Supported syntax (deliberately small — this is not a shell):
+ *   - `KEY=value`
+ *   - `export KEY=value` (the `export ` prefix is ignored)
+ *   - `# comment` lines and blank lines are skipped
+ *   - single- or double-quoted values are unquoted; `\n` and `\t` inside
+ *     double quotes become real newlines/tabs
+ *   - an unquoted value has a trailing ` # comment` stripped and is trimmed
+ *
+ * Lines that do not contain `=` are ignored rather than treated as errors, so a
+ * stray note in the file cannot break a build.
+ *
+ * @param content - Raw file contents.
+ * @returns Parsed variables in file order (later duplicates win).
+ */
+export function parseEnvLocal(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+
+    const withoutExport = line.startsWith("export ") ? line.slice(7).trim() : line;
+
+    const eq = withoutExport.indexOf("=");
+    if (eq <= 0) continue;
+
+    const key = withoutExport.slice(0, eq).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+
+    result[key] = parseValue(withoutExport.slice(eq + 1));
+  }
+
+  return result;
+}
+
+/**
+ * Unquotes and cleans up the right-hand side of a `KEY=value` line.
+ */
+function parseValue(raw: string): string {
+  const trimmed = raw.trim();
+
+  if (trimmed.startsWith('"')) {
+    const end = findClosingQuote(trimmed, '"');
+    if (end !== -1) {
+      return trimmed
+        .slice(1, end)
+        .replace(/\\n/g, "\n")
+        .replace(/\\t/g, "\t")
+        .replace(/\\"/g, '"');
+    }
+  }
+
+  if (trimmed.startsWith("'")) {
+    const end = findClosingQuote(trimmed, "'");
+    if (end !== -1) return trimmed.slice(1, end);
+  }
+
+  // Unquoted: strip an inline comment, then trim.
+  const commentAt = trimmed.search(/\s#/);
+  const body = commentAt === -1 ? trimmed : trimmed.slice(0, commentAt);
+  return body.trim();
+}
+
+/**
+ * Finds the index of the closing quote for a value that starts with `quote`,
+ * skipping backslash-escaped quotes. Returns -1 when unterminated.
+ */
+function findClosingQuote(value: string, quote: string): number {
+  for (let i = 1; i < value.length; i++) {
+    if (value[i] === "\\") {
+      i++;
+      continue;
+    }
+    if (value[i] === quote) return i;
+  }
+  return -1;
+}
+
+/** The outcome of an attempted env file load. */
+export type EnvLocalLoadResult = {
+  /** Absolute path checked. */
+  filePath: string;
+  /** True when the file existed and was read. */
+  loaded: boolean;
+  /** Names of variables that were injected into process.env. */
+  applied: string[];
+  /** Names present in the file but already set in the environment (left alone). */
+  skipped: string[];
+};
+
+/** The outcome of loading both env layers. */
+export type EnvFilesLoadResult = {
+  /** Result for the gitignored `.sous/.env.local` layer (loaded first, so it wins). */
+  local: EnvLocalLoadResult;
+  /** Result for the committed `.sous/.env` defaults layer (loaded second). */
+  defaults: EnvLocalLoadResult;
+};
+
+/**
+ * Loads a single env file into `env`, if it exists.
+ *
+ * A variable already present in `env` is never overwritten, which is what makes
+ * layering work: whoever gets there first wins.
+ *
+ * @param filePath - Absolute path to the env file.
+ * @param env - The environment object to mutate.
+ * @returns What was found and what was applied.
+ */
+function loadEnvFile(filePath: string, env: NodeJS.ProcessEnv): EnvLocalLoadResult {
+  if (!fs.existsSync(filePath)) {
+    return { filePath, loaded: false, applied: [], skipped: [] };
+  }
+
+  const parsed = parseEnvLocal(fs.readFileSync(filePath, "utf8"));
+  const applied: string[] = [];
+  const skipped: string[] = [];
+
+  for (const [key, value] of Object.entries(parsed)) {
+    if (env[key] !== undefined) {
+      skipped.push(key);
+      continue;
+    }
+    env[key] = value;
+    applied.push(key);
+  }
+
+  return { filePath, loaded: true, applied, skipped };
+}
+
+/**
+ * Loads `<sousDir>/.env` (committed shared defaults) into `process.env`, if it
+ * exists. Anything already set is left alone, so both your shell and
+ * `.env.local` outrank it.
+ *
+ * @param sousDir - The discovered `.sous/` directory.
+ * @param env - The environment object to mutate (injectable for tests).
+ * @returns What was found and what was applied.
+ */
+export function loadEnvDefaults(
+  sousDir: string,
+  env: NodeJS.ProcessEnv = process.env
+): EnvLocalLoadResult {
+  return loadEnvFile(path.join(sousDir, ENV_DEFAULTS_NAME), env);
+}
+
+/**
+ * Loads `<sousDir>/.env.local` (machine-specific values and secrets) into
+ * `process.env`, if it exists.
+ *
+ * Existing environment values always win: a variable already set in the real
+ * environment is never overwritten, so `FOO=bar xcv build` behaves as expected.
+ *
+ * @param sousDir - The discovered `.sous/` directory.
+ * @param env - The environment object to mutate (injectable for tests).
+ * @returns What was found and what was applied.
+ */
+export function loadEnvLocal(
+  sousDir: string,
+  env: NodeJS.ProcessEnv = process.env
+): EnvLocalLoadResult {
+  return loadEnvFile(path.join(sousDir, ENV_LOCAL_NAME), env);
+}
+
+/**
+ * Loads both env layers out of `sousDir`. Precedence, highest first:
+ *
+ *   real shell environment > `.sous/.env.local` > `.sous/.env`
+ *
+ * Because no load ever overwrites a value that is already set, the FIRST writer
+ * of a key wins. So the higher-precedence file is loaded first: `.env.local`,
+ * then `.env` fills in only the keys nobody else supplied. The real shell
+ * environment is already populated before either runs, so it outranks both.
+ *
+ * Must be called before any config or variable resolution so the `_env` block
+ * sees the injected values.
+ *
+ * @param sousDir - The discovered `.sous/` directory.
+ * @param env - The environment object to mutate (injectable for tests).
+ * @returns The per-file results.
+ */
+export function loadEnvFiles(
+  sousDir: string,
+  env: NodeJS.ProcessEnv = process.env
+): EnvFilesLoadResult {
+  const local = loadEnvLocal(sousDir, env);
+  const defaults = loadEnvDefaults(sousDir, env);
+  return { local, defaults };
+}