DEV Community

soil0119
soil0119

Posted on Fully Autonomous

Tracking code changes in plain folders with Where am I

#showdev #javascript #opensource

A source folder can contain several services, API definitions, and tests before it has a useful Git history. I have added plain-folder tracking to Where am I, an MIT-licensed tool for inspecting how code changes relate across local sources.

You can connect Git repositories and ordinary folders in the same workspace. The scanner runs locally, and a GitHub account is not required to analyze your sources.

Try the sample-data demo · Source code

How the folder baseline works

For a configured folder, the scanner discovers supported source files within its scan limits and records each readable file's content hash and line count.

The first scan establishes a baseline. A later scan compares that state with the previous one:

  • a new path is an added file;
  • a changed hash is a modified file;
  • a missing path is a deleted file.

Those file changes feed the existing static evidence graph and scan history. The graph can connect supported API patterns, handlers, callers, database access, documentation, and tests, with evidence available for inspection.

The implementation is in scripts/scan-repos.mjs, including scanFolder, buildFolderFileState, and compareFolderFileState. A synthetic regression fixture checks an initial baseline followed by file creation, modification, and deletion.

Connect a folder

Where am I requires Node.js 22.13 or newer. After following the README setup, add a source folder to whereami.config.json:

{
  "folders": [
    {
      "name": "sample-service",
      "path": "/absolute/path/to/sample-service"
    }
  ],
  "autoFetch": false
}
Enter fullscreen mode Exit fullscreen mode

Run npm run dev for the UI and local watcher, or npm run scan for a single scan. The initial folder scan reports a baseline; edit a supported file and rescan to inspect the change.

What the current baseline cannot tell you

The baseline advances with each scan. It stores hashes and line counts rather than old source text, so it cannot yet show a complete before-and-after line diff for a modified folder file. A same-length edit is detected through its changed hash, but its precise added and deleted lines need further work.

Static extraction is also approximate. Dynamic calls can be missed, and similar symbols or paths can produce incorrect relationships. Inspect the evidence and use tests and engineering judgment when reviewing a change.

Help improve the scanner

I have organized 64 scoped contributor tasks, each with a starting location, acceptance criteria, difficulty, and prerequisite links.

Smaller starting points include configuration diagnostics, making scan omissions visible, graph filters, and extractor fixture documentation.

Deeper work includes persistent folder checkpoints, incremental extraction, scope-aware JS/TS analysis, OpenAPI comparison, and new framework extractors. These are contribution candidates, not shipped capabilities.

If you try it, which missing connection would make it useful in your codebase? A small public or synthetic example of a false link or missed dependency is especially helpful.

Comment on an issue to discuss or claim a task. PR titles and descriptions must be written by the contributor in their own words; see CONTRIBUTING.md.

Disclosure: This post was prepared with AI assistance. The feature descriptions were checked against the repository; the public demo uses sample data.

Top comments (0)