@stigmer/cli 3.0.8

package/src/resources/ignore/defaults.ts

@@ -0,0 +1,155 @@
+// Built-in security-first ignore patterns, applied (lowest priority) unless
+// disabled. A verbatim port of the Go CLI's DefaultPatterns so `push` excludes
+// the same secrets, VCS metadata, and build artifacts on both CLIs.
+
+export const DEFAULT_PATTERNS: readonly string[] = [
+  // Version control
+  ".git/",
+  ".svn/",
+  ".hg/",
+  ".bzr/",
+
+  // Environment files (often contain secrets)
+  ".env",
+  ".env.*",
+  "!.env.example",
+  "!.env.template",
+  "!.env.sample",
+
+  // Private keys and certificates
+  "*.pem",
+  "*.key",
+  "*.p12",
+  "*.pfx",
+  "*.keystore",
+  "*.jks",
+  "id_rsa",
+  "id_rsa.*",
+  "id_ed25519",
+  "id_ed25519.*",
+  "id_dsa",
+  "id_dsa.*",
+
+  // Cloud credentials
+  "credentials.json",
+  "service-account*.json",
+  "gcp-credentials*.json",
+  "aws-credentials",
+  ".aws/credentials",
+  ".aws/config",
+
+  // Generic secrets
+  ".secrets",
+  ".secrets/",
+  "*.secret",
+  ".credentials/",
+  "secrets.yaml",
+  "secrets.yml",
+  "secrets.json",
+
+  // Package manager auth
+  ".npmrc",
+  ".pypirc",
+  ".gem/credentials",
+  ".docker/config.json",
+
+  // IDE and editor
+  ".idea/",
+  ".vscode/",
+  "*.swp",
+  "*.swo",
+  "*.swn",
+  "*~",
+  ".project",
+  ".classpath",
+  ".settings/",
+  "*.sublime-workspace",
+  "*.sublime-project",
+  ".vs/",
+
+  // Operating system
+  ".DS_Store",
+  ".DS_Store?",
+  "._*",
+  ".Spotlight-V100",
+  ".Trashes",
+  "Thumbs.db",
+  "Thumbs.db:encryptable",
+  "desktop.ini",
+  "ehthumbs.db",
+  "ehthumbs_vista.db",
+
+  // Node.js
+  "node_modules/",
+  "npm-debug.log*",
+  "yarn-debug.log*",
+  "yarn-error.log*",
+  ".npm/",
+  ".yarn/cache/",
+  ".yarn/unplugged/",
+  ".pnp.*",
+
+  // Python
+  "__pycache__/",
+  "*.py[cod]",
+  "*$py.class",
+  ".Python",
+  "*.so",
+  ".venv/",
+  "venv/",
+  "env/",
+  "ENV/",
+  ".pytest_cache/",
+  ".mypy_cache/",
+  ".ruff_cache/",
+  ".tox/",
+  ".nox/",
+  "*.egg-info/",
+  ".eggs/",
+  "dist/",
+  "build/",
+  "develop-eggs/",
+  ".installed.cfg",
+  "*.manifest",
+  "*.spec",
+  "pip-log.txt",
+  "pip-delete-this-directory.txt",
+
+  // Java/JVM
+  "target/",
+  "*.class",
+  "*.jar",
+  "*.war",
+  "*.ear",
+  ".gradle/",
+  "gradle-app.setting",
+  ".gradletasknamecache",
+
+  // Go
+  "vendor/",
+
+  // Rust
+  "target/",
+  "Cargo.lock",
+
+  // Coverage and test reports
+  "coverage/",
+  ".coverage",
+  "htmlcov/",
+  ".nyc_output/",
+  "coverage.xml",
+  "*.cover",
+  ".hypothesis/",
+
+  // Logs
+  "*.log",
+  "logs/",
+
+  // Temporary files
+  "tmp/",
+  "temp/",
+  "*.tmp",
+  "*.temp",
+  "*.bak",
+  "*.backup",
+];

package/src/resources/ignore/ignore.test.ts

@@ -0,0 +1,139 @@
+// Table tests for the gitignore-compatible ignore engine: the filepath.Match
+// port, the Pattern matcher (scoping, dir-only, globs, negation), and the
+// composed Matcher with source precedence + last-match-wins.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { matchName } from "./match.js";
+import { createMatcher } from "./matcher.js";
+import { MatchResult, parsePattern } from "./pattern.js";
+
+describe("matchName (filepath.Match port)", () => {
+  const cases: [string, string, boolean][] = [
+    ["*.go", "main.go", true],
+    ["*.go", "main.rs", false],
+    ["*", "anything", true],
+    ["a?c", "abc", true],
+    ["a?c", "ac", false],
+    ["[abc]", "b", true],
+    ["[abc]", "d", false],
+    ["[a-c]", "b", true],
+    ["[a-c]", "z", false],
+    ["[^a]", "b", true],
+    ["[^a]", "a", false],
+    ["foo*", "foobar", true],
+    ["*bar", "foobar", true],
+    ["h[a-z]llo", "hello", true],
+    ["node_modules", "node_modules", true],
+    ["\\*.go", "*.go", true],
+    // Malformed patterns: Go returns ErrBadPattern → callers treat as no match.
+    ["[", "a", false],
+    ["[a-", "a", false],
+  ];
+  for (const [pattern, name, expected] of cases) {
+    it(`${pattern} ~ ${name} => ${expected}`, () => {
+      expect(matchName(pattern, name)).toBe(expected);
+    });
+  }
+});
+
+describe("parsePattern / Pattern.match", () => {
+  it("directory-only patterns only match directories (or ancestors)", () => {
+    const p = parsePattern("node_modules/", []);
+    expect(p.match(["node_modules"], true)).toBe(MatchResult.Exclude);
+    expect(p.match(["node_modules"], false)).toBe(MatchResult.NoMatch);
+    expect(p.match(["src", "node_modules"], true)).toBe(MatchResult.Exclude);
+  });
+
+  it("simple name patterns match at any depth", () => {
+    const p = parsePattern("*.log", []);
+    expect(p.match(["app.log"], false)).toBe(MatchResult.Exclude);
+    expect(p.match(["sub", "app.log"], false)).toBe(MatchResult.Exclude);
+    expect(p.match(["app.txt"], false)).toBe(MatchResult.NoMatch);
+  });
+
+  it("leading slash anchors to the domain root", () => {
+    const p = parsePattern("/build", []);
+    expect(p.match(["build"], true)).toBe(MatchResult.Exclude);
+    expect(p.match(["src", "build"], true)).toBe(MatchResult.NoMatch);
+  });
+
+  it("** matches zero-to-many directories", () => {
+    const p = parsePattern("**/foo", []);
+    expect(p.match(["foo"], false)).toBe(MatchResult.Exclude);
+    expect(p.match(["a", "b", "foo"], false)).toBe(MatchResult.Exclude);
+    expect(p.match(["a", "bar"], false)).toBe(MatchResult.NoMatch);
+  });
+
+  it("negation patterns produce Include", () => {
+    const p = parsePattern("!keep.txt", []);
+    expect(p.inclusion).toBe(true);
+    expect(p.match(["keep.txt"], false)).toBe(MatchResult.Include);
+  });
+
+  it("domain scopes matching below a subtree", () => {
+    const p = parsePattern("*.txt", ["sub"]);
+    expect(p.match(["sub", "a.txt"], false)).toBe(MatchResult.Exclude);
+    expect(p.match(["a.txt"], false)).toBe(MatchResult.NoMatch);
+  });
+});
+
+describe("createMatcher (source precedence, last-match-wins)", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "ignore-test-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("applies security defaults including the .env.example negation", () => {
+    const m = createMatcher({ rootDir: dir, respectGitignore: false, includeDefaults: true });
+    expect(m.match(".env", false)).toBe(true);
+    expect(m.match(".env.example", false)).toBe(false);
+    expect(m.match("id_rsa", false)).toBe(true);
+    expect(m.match("node_modules", true)).toBe(true);
+  });
+
+  it("honors .gitignore with negation (last match wins)", () => {
+    writeFileSync(join(dir, ".gitignore"), "*.draft\n!keep.draft\n");
+    const m = createMatcher({ rootDir: dir, respectGitignore: true, includeDefaults: true });
+    expect(m.match("notes.draft", false)).toBe(true);
+    expect(m.match("keep.draft", false)).toBe(false);
+  });
+
+  it("ignores .gitignore when respectGitignore is false", () => {
+    writeFileSync(join(dir, ".gitignore"), "*.draft\n");
+    const m = createMatcher({ rootDir: dir, respectGitignore: false, includeDefaults: true });
+    expect(m.match("notes.draft", false)).toBe(false);
+  });
+
+  it(".stigmerignore is always loaded and outranks .gitignore", () => {
+    writeFileSync(join(dir, ".gitignore"), "!shared.draft\n");
+    writeFileSync(join(dir, ".stigmerignore"), "*.draft\n");
+    const m = createMatcher({ rootDir: dir, respectGitignore: true, includeDefaults: true });
+    expect(m.match("shared.draft", false)).toBe(true);
+  });
+
+  it("CLI extra ignore/include override file sources", () => {
+    writeFileSync(join(dir, ".gitignore"), "*.draft\n");
+    const m = createMatcher({
+      rootDir: dir,
+      respectGitignore: true,
+      includeDefaults: true,
+      extraIgnore: ["*.tmp"],
+      extraInclude: ["important.draft"],
+    });
+    expect(m.match("scratch.tmp", false)).toBe(true);
+    expect(m.match("important.draft", false)).toBe(false);
+  });
+
+  it("reports the matching source and reason", () => {
+    const m = createMatcher({ rootDir: dir, respectGitignore: false, includeDefaults: true });
+    const reason = m.matchWithReason(".env", false);
+    expect(reason.ignored).toBe(true);
+    expect(reason.source).toBe("defaults");
+  });
+});

package/src/resources/ignore/index.ts

@@ -0,0 +1,17 @@
+// Public surface of the gitignore-compatible ignore engine.
+
+export { DEFAULT_PATTERNS } from "./defaults.js";
+export { matchName } from "./match.js";
+export {
+  createMatcher,
+  type MatcherOptions,
+  type MatchReason,
+  Matcher,
+  Reason,
+  REASON_TEXT,
+  SOURCE_CLI,
+  SOURCE_DEFAULTS,
+  SOURCE_GITIGNORE,
+  SOURCE_STIGMERIGNORE,
+} from "./matcher.js";
+export { MatchResult, type Pattern, parsePattern } from "./pattern.js";

package/src/resources/ignore/match.ts

@@ -0,0 +1,158 @@
+// Faithful port of Go's path/filepath Match, used by the gitignore pattern
+// engine to match a single glob against a single path component.
+//
+// The separator is fixed to "/" (paths are normalized to forward slashes and
+// individual components never contain a separator). Matching operates on UTF-16
+// code units rather than runes — correct for the ASCII glob syntax gitignore
+// patterns use; exotic multi-byte classes are out of scope.
+//
+// Go returns ErrBadPattern for malformed patterns; every go-git caller treats
+// that as "no match", so `matchName` swallows the error and returns false.
+
+const SEPARATOR = "/";
+
+class BadPatternError extends Error {}
+
+/** Match `name` against the glob `pattern` (Go filepath.Match semantics). */
+export function matchName(pattern: string, name: string): boolean {
+  try {
+    return matchImpl(pattern, name);
+  } catch (err) {
+    if (err instanceof BadPatternError) return false;
+    throw err;
+  }
+}
+
+function matchImpl(pattern: string, name: string): boolean {
+  outer: while (pattern.length > 0) {
+    const [star, chunk, rest] = scanChunk(pattern);
+    pattern = rest;
+
+    if (star && chunk === "") {
+      // Trailing `*` matches the rest of the component (which has no separator).
+      return !name.includes(SEPARATOR);
+    }
+
+    const [t, ok] = matchChunk(chunk, name);
+    if (ok && (t.length === 0 || pattern.length > 0)) {
+      name = t;
+      continue;
+    }
+
+    if (star) {
+      for (let i = 0; i < name.length && name[i] !== SEPARATOR; i++) {
+        const [t2, ok2] = matchChunk(chunk, name.slice(i + 1));
+        if (ok2) {
+          if (pattern.length === 0 && t2.length > 0) continue;
+          name = t2;
+          continue outer;
+        }
+      }
+    }
+    return false;
+  }
+  return name.length === 0;
+}
+
+function scanChunk(pattern: string): [boolean, string, string] {
+  let star = false;
+  while (pattern.length > 0 && pattern[0] === "*") {
+    pattern = pattern.slice(1);
+    star = true;
+  }
+
+  let inrange = false;
+  let i = 0;
+  scan: for (i = 0; i < pattern.length; i++) {
+    switch (pattern[i]) {
+      case "\\":
+        if (i + 1 < pattern.length) i++;
+        break;
+      case "[":
+        inrange = true;
+        break;
+      case "]":
+        inrange = false;
+        break;
+      case "*":
+        if (!inrange) break scan;
+        break;
+    }
+  }
+  return [star, pattern.slice(0, i), pattern.slice(i)];
+}
+
+function matchChunk(chunk: string, s: string): [string, boolean] {
+  let failed = false;
+  while (chunk.length > 0) {
+    if (!failed && s.length === 0) failed = true;
+
+    const c = chunk[0];
+    if (c === "[") {
+      let r = "";
+      if (!failed) {
+        r = s[0];
+        s = s.slice(1);
+      }
+      chunk = chunk.slice(1);
+      let negated = false;
+      if (chunk.length > 0 && chunk[0] === "^") {
+        negated = true;
+        chunk = chunk.slice(1);
+      }
+      let match = false;
+      let nrange = 0;
+      for (;;) {
+        if (chunk.length > 0 && chunk[0] === "]" && nrange > 0) {
+          chunk = chunk.slice(1);
+          break;
+        }
+        let lo: string;
+        [lo, chunk] = getEsc(chunk);
+        let hi = lo;
+        if (chunk[0] === "-") {
+          [hi, chunk] = getEsc(chunk.slice(1));
+        }
+        if (lo <= r && r <= hi) match = true;
+        nrange++;
+      }
+      if (match === negated) failed = true;
+    } else if (c === "?") {
+      if (!failed) {
+        if (s[0] === SEPARATOR) failed = true;
+        s = s.slice(1);
+      }
+      chunk = chunk.slice(1);
+    } else if (c === "\\") {
+      chunk = chunk.slice(1);
+      if (chunk.length === 0) throw new BadPatternError("bad pattern");
+      if (!failed) {
+        if (chunk[0] !== s[0]) failed = true;
+        s = s.slice(1);
+      }
+      chunk = chunk.slice(1);
+    } else {
+      if (!failed) {
+        if (chunk[0] !== s[0]) failed = true;
+        s = s.slice(1);
+      }
+      chunk = chunk.slice(1);
+    }
+  }
+  if (failed) return ["", false];
+  return [s, true];
+}
+
+function getEsc(chunk: string): [string, string] {
+  if (chunk.length === 0 || chunk[0] === "-" || chunk[0] === "]") {
+    throw new BadPatternError("bad pattern");
+  }
+  if (chunk[0] === "\\") {
+    chunk = chunk.slice(1);
+    if (chunk.length === 0) throw new BadPatternError("bad pattern");
+  }
+  const r = chunk[0];
+  const nchunk = chunk.slice(1);
+  if (nchunk.length === 0) throw new BadPatternError("bad pattern");
+  return [r, nchunk];
+}

package/src/resources/ignore/matcher.ts

@@ -0,0 +1,158 @@
+// Ignore matcher: composes pattern sources with gitignore precedence (defaults
+// → .gitignore → .stigmerignore → CLI flags), evaluating "last match wins".
+// A faithful port of the Go CLI's pkg/ignore Matcher.
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_PATTERNS } from "./defaults.js";
+import { MatchResult, type Pattern, parsePattern } from "./pattern.js";
+
+export const SOURCE_DEFAULTS = "defaults";
+export const SOURCE_GITIGNORE = ".gitignore";
+export const SOURCE_STIGMERIGNORE = ".stigmerignore";
+export const SOURCE_CLI = "cli";
+
+export enum Reason {
+  NoMatch = 0,
+  Excluded = 1,
+  Included = 2,
+  DefaultDeny = 3,
+}
+
+export const REASON_TEXT: Readonly<Record<Reason, string>> = {
+  [Reason.NoMatch]: "no pattern matched",
+  [Reason.Excluded]: "excluded by pattern",
+  [Reason.Included]: "included by negation pattern",
+  [Reason.DefaultDeny]: "excluded by security default",
+};
+
+export interface MatchReason {
+  readonly ignored: boolean;
+  readonly reason: Reason;
+  readonly source: string;
+  readonly pattern: string;
+}
+
+interface PatternEntry {
+  readonly pattern: Pattern;
+  readonly source: string;
+  readonly raw: string;
+}
+
+export interface MatcherOptions {
+  readonly rootDir: string;
+  readonly respectGitignore: boolean;
+  readonly includeDefaults: boolean;
+  readonly extraIgnore?: readonly string[];
+  readonly extraInclude?: readonly string[];
+}
+
+export class Matcher {
+  private readonly entries: readonly PatternEntry[];
+
+  constructor(entries: readonly PatternEntry[]) {
+    this.entries = entries;
+  }
+
+  /** Decide whether a path (relative, forward-slash) is ignored, with reason. */
+  matchWithReason(path: string, isDir: boolean): MatchReason {
+    const components = pathToComponents(path);
+    if (components.length === 0) {
+      return { ignored: false, reason: Reason.NoMatch, source: "", pattern: "" };
+    }
+
+    let lastMatch: PatternEntry | undefined;
+    let lastResult = MatchResult.NoMatch;
+    for (const entry of this.entries) {
+      const result = entry.pattern.match(components, isDir);
+      if (result !== MatchResult.NoMatch) {
+        lastMatch = entry;
+        lastResult = result;
+      }
+    }
+
+    if (lastMatch === undefined) {
+      return { ignored: false, reason: Reason.NoMatch, source: "", pattern: "" };
+    }
+
+    if (lastResult === MatchResult.Exclude) {
+      const reason = lastMatch.source === SOURCE_DEFAULTS ? Reason.DefaultDeny : Reason.Excluded;
+      return { ignored: true, reason, source: lastMatch.source, pattern: lastMatch.raw };
+    }
+    // Include (negation): explicitly un-ignored.
+    return { ignored: false, reason: Reason.Included, source: lastMatch.source, pattern: lastMatch.raw };
+  }
+
+  /** Whether the path should be excluded from the artifact. */
+  match(path: string, isDir: boolean): boolean {
+    return this.matchWithReason(path, isDir).ignored;
+  }
+
+  /** All loaded patterns as "[source] pattern" (for dry-run diagnostics). */
+  patterns(): string[] {
+    return this.entries.map((entry) => `[${entry.source}] ${entry.raw}`);
+  }
+}
+
+/** Build a Matcher for `rootDir`, loading the configured pattern sources. */
+export function createMatcher(options: MatcherOptions): Matcher {
+  if (options.rootDir === "") throw new Error("rootDir is required");
+  const stat = statSync(options.rootDir);
+  if (!stat.isDirectory()) throw new Error(`rootDir is not a directory: ${options.rootDir}`);
+
+  const entries: PatternEntry[] = [];
+  if (options.includeDefaults) {
+    entries.push(...parseEntries(DEFAULT_PATTERNS, SOURCE_DEFAULTS));
+  }
+  if (options.respectGitignore) {
+    entries.push(...loadIgnoreFile(join(options.rootDir, ".gitignore"), SOURCE_GITIGNORE));
+  }
+  entries.push(...loadIgnoreFile(join(options.rootDir, ".stigmerignore"), SOURCE_STIGMERIGNORE));
+
+  const extraIgnore = options.extraIgnore ?? [];
+  const extraInclude = options.extraInclude ?? [];
+  if (extraIgnore.length > 0 || extraInclude.length > 0) {
+    entries.push(...loadCliPatterns(extraIgnore, extraInclude));
+  }
+
+  return new Matcher(entries);
+}
+
+function parseEntries(patterns: readonly string[], source: string): PatternEntry[] {
+  const entries: PatternEntry[] = [];
+  for (const raw of patterns) {
+    const trimmed = raw.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    entries.push({ pattern: parsePattern(trimmed, []), source, raw: trimmed });
+  }
+  return entries;
+}
+
+function loadIgnoreFile(path: string, source: string): PatternEntry[] {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    // Absent or unreadable ignore files are normal — no patterns.
+    return [];
+  }
+  return parseEntries(text.split(/\r?\n/), source);
+}
+
+function loadCliPatterns(ignore: readonly string[], include: readonly string[]): PatternEntry[] {
+  const entries = parseEntries(ignore, SOURCE_CLI);
+  const negations: string[] = [];
+  for (const pattern of include) {
+    const trimmed = pattern.trim();
+    if (trimmed === "") continue;
+    negations.push(trimmed.startsWith("!") ? trimmed : `!${trimmed}`);
+  }
+  entries.push(...parseEntries(negations, SOURCE_CLI));
+  return entries;
+}
+
+function pathToComponents(path: string): string[] {
+  const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (normalized === "" || normalized === ".") return [];
+  return normalized.split("/");
+}