[review only — do not merge] Snapshot: dev state across work streams

[ageem23]

Internal review-only PR. Not for merge.

Goal: get CodeRabbit findings on the snapshot commit (semantic title-filter phase, LinkedIn provider, triage/scoring utilities, scan.mjs round-3 edits, small system touch-ups) before splitting into focused per-feature branches for upstream PRs.

Each work stream listed in the snapshot commit message will be split into its own branch from upstream/main once findings are addressed.

Summary by CodeRabbit

Release Notes

• New Features

  • Added LinkedIn job source provider with authentication, session management, and automated job scraping
  • Enhanced title filtering with AI-powered semantic analysis as fallback for non-matching titles
  • New CLI tools: filter pattern analyzer, LinkedIn configuration validator, and pipeline score updater

• Documentation

  • Extended provider contract documentation with authentication lifecycle hooks and semantic options
  • Enhanced configuration templates with LinkedIn setup and semantic filtering guidance

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (1)

• main

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 2f76bc54-9449-4fef-8e72-93198349bafd

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch personal/dev-snapshot

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ageem23]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 17

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

batch/batch-runner.sh (1)

73-81: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Guard --model before reading $2.

With set -u, invoking the script as batch-runner.sh --model aborts on an unbound $2 instead of producing a usable error. Please validate that a value is present before assigning MODEL here (ideally with the same guard for the other value-taking flags in this parser).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@batch/batch-runner.sh` around lines 73 - 81, The flag parser currently
assigns value-taking flags (e.g., --model -> MODEL) without verifying that a
following argument exists, which causes an unbound variable error under set -u;
update the case branches that consume a value (at least the --model branch, and
ideally --parallel, --start-from, --max-retries, --min-score) to check that a
value is present (for example test that $# -ge 2 or that "${2-}" is non-empty)
before assigning MODEL="$2" and shifting, and if the value is missing emit a
clear usage/error message and exit non-zero.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.gitignore:
- Line 23: Remove the overly-broad ignore entry "batch/*" from .gitignore
because it causes system files like batch/batch-runner.sh to be ignored,
prevents negation entries such as "!batch/logs/.gitkeep" and
"!batch/tracker-additions/.gitkeep" from re-including files, and makes the
earlier "batch/bat*" pattern redundant; keep the existing specific patterns (the
entries around "batch/bat*", "!batch/logs/.gitkeep", and
"!batch/tracker-additions/.gitkeep") and delete the "batch/*" line so system and
explicitly negated files remain tracked.

In `@analyze-filter-patterns.mjs`:
- Around line 36-43: The CLI numeric flags may produce NaN via parseInt
(including when a flag is present with no value); update the parsing around
argValue, sinceDays, minFreq, and topN to validate the returned value: after
calling argValue('--since','30') etc., attempt to parseInt and then check
Number.isFinite(result) and result > 0 (or other domain constraints), and if
invalid either fall back to the default or throw/exit with a clear usage error
message; also ensure argValue detects the “flag present but no next token” case
(i.e., args.indexOf(flag) returns last index) and treat that as invalid so you
log/exit rather than propagating NaN into downstream date math and threshold
logic.

In `@dashboard/main.go`:
- Around line 29-42: Remove the fixed "i < 6" cap and instead loop until the
filesystem root by using an infinite loop that updates parent :=
filepath.Dir(cur) and breaks when parent == cur; for each filepath.Join(cur,
"applications.md") and filepath.Join(cur, "data", "applications.md") call use
os.Stat and if err == nil return cur; if err != nil and !os.IsNotExist(err)
treat it as a real filesystem error (do not silently treat it as "not found") —
for example return start (preserving existing behavior) or propagate/log the
error — and only ignore errors where os.IsNotExist(err) is true so the search
continues up to the root.

In `@modes/contacto.md`:
- Around line 65-79: The "Name verification gate" block is written in English
inside a primarily Spanish mode and should be made language-consistent: either
translate the entire "Name verification gate (MANDATORY — do this BEFORE
presenting the message to the user):" section (including checks 1–4: Exact-match
check, No-substitution check, Right-person check, Present format) into Spanish
so it matches the rest of the contacto mode, or move this gate into a
language-specific file for English; ensure the translated terms and the example
salutation line (“Sending to: {Full Name} ({linkedin URL}) — addressing them as
"{salutation in message}"”) preserve the exact verification steps and the
instruction to STOP and ask for confirmation if any check fails.
- Around line 74-77: Update the "Present format" guidance so the "Sending to"
line is explicitly described as a pre-send verification header and not part of
the outbound LinkedIn message body or its 300‑character limit; specifically
modify the "Present format" block (the one that shows: **Sending to:** {Full
Name} ({linkedin URL}) — addressing them as "{salutation in message}") to state
it is metadata only, must be displayed above the message for verification, must
not be copied into the message body, and must not be counted against the
300‑char message limit.

In `@providers/linkedin.mjs`:
- Around line 224-236: The unwrapRedirect function currently accepts any URL
scheme when decoding the nested LinkedIn redirect; update the validation so that
after parsing the decoded value (the variable decoded) into a URL object you
explicitly check the URL's protocol and only accept 'http:' or 'https:'—if the
protocol is anything else, return the original trimmed href; ensure this check
happens inside the try block after creating the URL and before returning decoded
(and keep existing fallback returns intact).
- Around line 211-217: slugify currently can return an empty string for
non-Latin titles, causing saveJd to write to jds/.md and collide; update slugify
(or the caller saveJd) to fall back to a stable non-empty identifier when
slugify(text) === '' (e.g., compute a short stable hash of the original text or
use a deterministic UID derived from the title/company and timestamp) and use
that fallback for file names/URLs; additionally, respect language modes by
detecting German/French/Japanese postings and, if config/profile.yml has
language.modes_dir set (e.g., modes/de, modes/fr, modes/ja), load modes from
that directory instead of default modes/ to suggest appropriate language modes.

In `@scan-semantic.mjs`:
- Around line 89-93: The current fallback finds braceStart and braceEnd using
lastIndexOf which can include extra trailing braces; instead scan forward from
braceStart to find the matching closing brace by tracking a depth counter
(increment on '{', decrement on '}') and stop when depth returns to zero to get
the index of the first balanced object, then call JSON.parse on
text.slice(braceStart, matchingIndex + 1); update the code around
braceStart/braceEnd and the JSON.parse call to use this matchingIndex approach
so only the first balanced JSON object is parsed.
- Around line 130-131: hasSemanticBackend currently swallows errors from
resolveBackend (hiding bad CAREER_OPS_SEMANTIC_BACKEND overrides); change it to
let invalid override errors propagate (or return a structured Error) instead of
returning null—i.e., remove the empty catch that returns null and either rethrow
the caught error from hasSemanticBackend or return an object like { error } so
callers can log it before falling back; update references to
hasSemanticBackend/resolveBackend (and any callers expecting null) to handle the
propagated error or structured error accordingly.

In `@scan.mjs`:
- Around line 271-298: The code allows a bare "--login" to slip through because
loginProviderId can be undefined; update the login handling to detect when the
flag is present but no provider id was supplied (check loginFlag !== -1 &&
!loginProviderId) and immediately print a usage/error message and exit (set
process.exitCode = 1 and return or process.exit(1)). Place this check before
calling providers.get(loginProviderId) and before invoking provider.login(),
referencing the existing loginFlag and loginProviderId symbols so a missing
value fails fast instead of continuing into the normal scan path.

In `@templates/portals.example.yml`:
- Around line 30-35: The comment in the semantic phase block is misleading about
override precedence; update the text so it explicitly states the actual
resolution order used at runtime: first check the CAREER_OPS_SEMANTIC_BACKEND
environment variable, then check for ANTHROPIC_API_KEY, then look for the
`claude` CLI in PATH, and if none are available neutrals are rejected; mention
the possible values for CAREER_OPS_SEMANTIC_BACKEND (api|cli) and reference the
semantic phase/title filtering to make intent clear.
- Around line 119-123: The comment for the archetypes block incorrectly states
it is used only when ANTHROPIC_API_KEY is set; update the text to reflect that
the archetypes are consumed by both API and CLI semantic flows
(scan-semantic.mjs passes archetypes to both backends). Edit the archetypes
description to remove the "only" qualifier and explicitly note that these
canonical role-family descriptions are used by the semantic phase for both the
API and Claude CLI paths so users know the section is not ignored when using the
CLI.

In `@test-linkedin-config.mjs`:
- Around line 136-140: After calling loadConfig(), validate that
config?.tracked_companies is an array before using .map(): if config is missing
or tracked_companies is undefined treat it as an empty array, but if
tracked_companies exists and is not an Array, log an error and exit process with
code 2; update the code around the variables config, entries and linkedinEntries
(the block that sets const config = loadConfig(); const entries =
config?.tracked_companies || []; const linkedinEntries = ...) to perform an
explicit Array.isArray check and handle the non-array case as described.
- Around line 112-120: The KNOWN set advertises delay_pages and delay_searches
as supported but the validator in test-linkedin-config.mjs never checks their
shapes, which causes providers/linkedin.mjs to later assume a [min,max] tuple
and fail; update the validation loop to validate that entry.delay_pages and
entry.delay_searches (when present) are arrays of two numeric values with
min<=max (or else push a warning/error), or remove those keys from the KNOWN set
if you choose not to validate them; reference the KNOWN constant and the entry
object in test-linkedin-config.mjs and ensure compatibility with the tuple
expectation in providers/linkedin.mjs.

In `@triage-pending.mjs`:
- Around line 188-206: The location-scoring logic in the triage code hardcodes a
Chicago-first, US-remote preference (see the location variable, the regex checks
and the score/breakdown mutations) which should instead read per-user geo
preferences from profile config; update the scorer to load the profile's geo
preferences (e.g., include allowlist/denylist, remote-preference, and
preferred-US-hubs) from config/profile.yml or the profile API and replace the
inlined regex/weights with a small policy evaluator that applies those
configured rules to entry.location, then adjust score and breakdown accordingly
(keep the same score/breakdown API but derive +5/+3/-10 etc. from config values
rather than hardcoded literals and remove the fixed Chicago/IL assumptions).

In `@update-pipeline-scores.mjs`:
- Around line 13-24: The script currently calls fs.readFileSync(STATE) and
fs.readdirSync(REPORTS) unguarded and will crash on a clean checkout; modify the
logic around STATE/REPORTS so missing artifacts are treated as empty input:
check existence (fs.existsSync or try/catch) before reading and if STATE is
missing set stateLines = [] (so urlMap stays empty) and if REPORTS is missing
set reportFiles = [] (or skip report processing), then return/exit early or
no-op the update step so the pipeline is left untouched; update references to
stateLines, urlMap, and reportFiles accordingly to handle empty arrays.
- Around line 38-40: findUrl currently only matches http(s) URLs so
"local:jds/..." links get dropped when rewriting pipeline; update the findUrl
function to recognize and return local:jds/... URIs as well (e.g. match either
https?://\S+ or local:jds/\S+ using a single regex) so callers that rewrite
entries (the code paths around the existing findUrl and the logic in the 56-76
region) will preserve those local:jds links.

---

Outside diff comments:
In `@batch/batch-runner.sh`:
- Around line 73-81: The flag parser currently assigns value-taking flags (e.g.,
--model -> MODEL) without verifying that a following argument exists, which
causes an unbound variable error under set -u; update the case branches that
consume a value (at least the --model branch, and ideally --parallel,
--start-from, --max-retries, --min-score) to check that a value is present (for
example test that $# -ge 2 or that "${2-}" is non-empty) before assigning
MODEL="$2" and shifting, and if the value is missing emit a clear usage/error
message and exit non-zero.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1ce9e49a-3afd-4c87-af73-375e7d082103

📥 Commits

Reviewing files that changed from the base of the PR and between 7f77834 and 410961c.

📒 Files selected for processing (14)

• .gitignore
• CLAUDE.md
• analyze-filter-patterns.mjs
• batch/batch-runner.sh
• dashboard/main.go
• modes/contacto.md
• package.json
• providers/linkedin.mjs
• scan-semantic.mjs
• scan.mjs
• templates/portals.example.yml
• test-linkedin-config.mjs
• triage-pending.mjs
• update-pipeline-scores.mjs