simple-data-analysis

Imported from nshiab/simple-data-analysis (AGENTS.md). Install upstream with npx skills add nshiab/simple-data-analysis. Copyright stays with the author.

Development Workflow

• Naming: Use a few descriptive words about the feature, fix, or bug for branch names and PR titles; never include Codex, Claude, or other AI agent names.
• Attribution: Never credit AI agents as authors or co-authors in commits or PRs, including Co-authored-by trailers.

Phase 1: Exploration (BEFORE Modifying)

• Library Architecture: SDA is split into two packages.
  • simple-data-analysis-core contains all core DuckDB-dependent logic (loading, filtering, joining, geospatial, etc.).
  • simple-data-analysis (this repo) is an extension adding AI, Google Sheets, and Dataviz features and more.
• Where to contribute:
  • Prefer simple-data-analysis-core for features that depend only on DuckDB or have no external runtime dependencies.
  • Prefer simple-data-analysis for features requiring a runtime library beyond DuckDB, such as AI, Google Sheets, or charting integrations.
• Analyze Structure: Review the directory tree to understand the module hierarchy.
• Check Capabilities: Read deno.json to identify available tasks and import maps. Always use the defined import aliases and include file extensions (e.g., .ts) in imports.
• Consistency Check: Examine existing implementations of similar properties/methods/parameters. Match the existing design patterns and naming conventions exactly.
• Architectural Placement: If the logic is a generic utility, place it in src/helpers/. If the logic is domain-specific, place it within the relevant class/file. If the utility is potentially useful for core, consider moving it to the core repo instead.

Phase 2: Implementation (DURING Development)

• Public API Organization: Give every public method a matching implementation file at src/methods/<methodName>.ts and test file at test/unit/methods/<methodName>.test.ts. Shared internal logic may live in a separate module whose filename matches its exported function.
• Inline Public Types: Define the complete type of every object-shaped public parameter inline in the public signature. Recursively inline nested object-shaped types, aliases, and interfaces within options. Public option signatures must not reference named application types. Built-in types such as Promise, Date, and URL may remain named. Implementation-only functions may use reusable named aliases. Keep internal named types colocated with the implementation that owns them, and do not re-export them from public index.ts files.
• Strict Typing: Avoid any. Use explicit interfaces and types.
• Documentation: Every new public property, method, or parameter must have a JSDoc block.

  • Include a clear description.

  • Include at least one @example.

  • In examples that produce a table, chain table operations and finish the chain with .log(). If direct chaining is unavailable, finish the example with await table.log().

    await table
      .selectColumns(["name", "salary"])
      .log();

  • Update @param and @returns tags accurately.

  • Match existing JSDoc block styling.

  • If modifying existing code, ensure all related JSDoc remains synchronized with the logic.

Phase 3: Validation (AFTER Modifying)

• Code Quality: Run deno lint, deno fmt, and deno check. All must pass without warnings.
• Testing:
  • Update existing tests in test/unit/ or create a new .test.ts file if none exists. The test/unit/ folder should mirror the test/src/ folder.
  • Run tests using deno test (or the specific deno task defined in deno.json).
• Documentation Integrity: Ensure JSDoc remains accurate if you have to modify the code to pass the tests.

Files to ignore

Do not manually edit llm.md, as it is autogenerated from your JSDoc comments.