neosloc/neosloc

Can another program use it through a documented, machine-readable surface?

• next: [library] L2 The public API is delimited (__all__, an exports map, exported identifiers). (no __all__/exports defining the public API)

cli ladder · level 4

• ✓ L1 Invocable non-interactively: no prompts, or prompts guarded by a TTY check or a --yes/--no-input option. no interactive prompts
• ✓ L2 --help documents every option (at least 90% of options have help text). neosloc/cli.py options with help text
• ✓ L3 Machine-readable output (--json/--format) and documented exit statuses. neosloc/cli.py 2 matchesdocs/json.md 1 match
• ✓ L4 The output format is specified by a JSON Schema. neosloc/schema.py 2 matches

library ladder · level 1

• ✓ L1 An importable, packaged API exists. pyproject.toml Python package neosloc
• ✗ L2 The public API is delimited (__all__, an exports map, exported identifiers). no __all__/exports defining the public API
• ✗ L3 The public API is statically typed (py.typed, type declarations, a typed language). no py.typed or type declarations
• ✗ L4 An API reference is generated from the code (autodoc, mkdocstrings, typedoc, …). no generated API reference

Can integrators rely on it not changing under them?

• next: L3 A deprecation mechanism is used in code (warnings, @deprecated, Deprecation/Sunset headers) or the API is versioned. (no deprecation mechanism or API versioning)

all ladder · level 2

• ✓ L1 Releases are versioned (semver tags or versioned changelog sections). 12 semver tags, latest v0.8.0
• ✓ L2 A changelog exists and marks breaking changes. CHANGELOG.md marks breaking changes
• ✗ L3 A deprecation mechanism is used in code (warnings, @deprecated, Deprecation/Sunset headers) or the API is versioned. no deprecation mechanism or API versioning
• ✓ L4 Across tagged releases, no OpenAPI operation, CLI option or __all__ symbol was removed without first being deprecated. 12 tagged releases compared

Can others react to state changes without polling?

Can a machine act with its own revocable, least-privilege identity?

• next: [cli] L2 Credentials never need to be on the command line, and their environment variables are documented. (--auth-header takes a secret on the command line (visible in shell history and ps))
• next: [library] L4 Several profiles or scoped credentials per target. (no credential profiles)

cli ladder · level 1

• ✓ L1 Credentials can be supplied non-interactively (environment variables). neosloc/agentic/llm.py 1 match
• ✗ L2 Credentials never need to be on the command line, and their environment variables are documented. --auth-header takes a secret on the command line (visible in shell history and ps)
• ✓ L3 No output or log statement includes a credential. no credential in print/log statements
• ✗ L4 Several profiles or scoped credentials per target. no credential profiles

library ladder · level 3

• ✓ L1 Credentials can be supplied non-interactively (environment variables). neosloc/agentic/llm.py 1 match
• ✓ L2 The credential environment variables are documented. README.md 1 matchdocs/evaluators.md 1 match
• ✓ L3 No output or log statement includes a credential. no credential in print/log statements
• ✗ L4 Several profiles or scoped credentials per target. no credential profiles

Can its data get in and out, in bulk, in open formats, with an explicit schema?

Can an automated caller use it without guessing, and recover from failure?

• next: [cli] L4 --dry-run, limits for long or costly operations (timeouts, budgets), and agent docs. (no --dry-run)
• next: [library] L4 Agent docs, and examples that run as tests (doctests). (examples don't run as tests)

cli ladder · level 3

• ✓ L1 Never blocks on a prompt when stdin is not a TTY. no interactive prompts
• ✓ L2 Data on stdout, diagnostics on stderr, non-zero exit on failure. neosloc/log.py 11 matchesneosloc/errors.py 7 matches
• ✓ L3 Documented exit statuses distinguish error classes, errors are JSON in JSON mode, and color is off when not a TTY. docs/json.md 1 matchneosloc/cli.py help text
• ✗ L4 --dry-run, limits for long or costly operations (timeouts, budgets), and agent docs. no --dry-run

library ladder · level 3

• ✓ L1 Errors are specific exception types, and library code never calls sys.exit. neosloc/errors.py 5 matchesneosloc/agentic/llm.py 1 match
• ✓ L2 Inputs are validated with messages naming the bad argument. neosloc/agentic/llm.py 13 matchesneosloc/agentic/workspace.py 6 matches
• ✓ L3 Timeouts and retries are configurable. neosloc/agentic/llm.py 3 matchesneosloc/agentic/workspace.py 1 match
• ✗ L4 Agent docs, and examples that run as tests (doctests). examples don't run as tests

Can another system run and compose it without a human?

• next: [cli] L4 Also shipped as a container image or a single binary. (no container image or binary)

cli ladder · level 3

• ✓ L1 Runnable from source (a declared entry point). pyproject.toml console script
• ✓ L2 Installable as a package that provides the command. pyproject.toml console script
• ✓ L3 Published to a public registry and run non-interactively in CI. .github/workflows/release.yml 1 match.github/workflows/ci.yml 6 matches
• ✗ L4 Also shipped as a container image or a single binary. no container image or binary

library ladder · level 4

• ✓ L1 Importable from source. pyproject.toml Python package neosloc
• ✓ L2 Installable as a package (a package manifest). pyproject.toml package manifest
• ✓ L3 Published to a public registry, with at most 10 runtime dependencies. .github/workflows/release.yml 1 match 0 runtime dependencies
• ✓ L4 Optional features behind extras/features. pyproject.toml 1 match

Can behaviour be added without modifying the code?

• next: L3 Out-of-tree extensions are discovered (entry points, a plugin directory, configuration) without editing the package. (extensions must be added inside the package)

all ladder · level 2

• ✓ L1 Internal seams: a registry, registration function or plugin manager. neosloc/ladder.py 1 match
• ✓ L2 The docs show how to add behaviour through those seams (even in-tree). docs/extending.md 3 matches
• ✗ L3 Out-of-tree extensions are discovered (entry points, a plugin directory, configuration) without editing the package. extensions must be added inside the package
• ✗ L4 The extension API is versioned, has lifecycle hooks, and has example extensions. the extension API isn't versioned

Can an operator, or an orchestrating agent, tell whether it works and why not?

• next: [cli] L4 Tracing hooks (OpenTelemetry). (no tracing hooks)
• next: [library] L2 Log levels are used meaningfully (at least two levels). (fewer than two log levels used)

cli ladder · level 3

• ✓ L1 Meaningful exit statuses, and errors on stderr. neosloc/log.py 11 matchesneosloc/errors.py 7 matches
• ✓ L2 Verbosity control for diagnostics (--quiet, --log-level, --debug). neosloc/cli.py 3 matches
• ✓ L3 Structured logs (e.g. --log-format json) or a machine-readable run summary. neosloc/cli.py 1 matchneosloc/log.py 1 match
• ✗ L4 Tracing hooks (OpenTelemetry). no tracing hooks

library ladder · level 1

• ✓ L1 Logs through a standard logger namespace and never prints from library code. neosloc/log.py 1 match no print() in library code
• ✗ L2 Log levels are used meaningfully (at least two levels). fewer than two log levels used
• ✗ L3 Optional metrics or tracing hooks. no metrics or tracing hooks
• ✗ L4 OpenTelemetry instrumentation available. no OpenTelemetry instrumentation

Can an agent change it safely with limited context?

• next: L3 At least 90% of modules fit 32k tokens and no file exceeds 12k; test/source token ratio at least 0.3; at least 70% of the code is typed. (50% of modules fit 32k tokens; 1 files over 12k)

all ladder · level 2

• ✓ L1 A README and some tests. README.mdtests/test_agentic.py 10 test files
• ✓ L2 CI runs the tests; applications pin dependencies (libraries and zero-dependency projects are exempt). .github/workflows/ci.yml.github/workflows/docs.yml
• ✗ L3 At least 90% of modules fit 32k tokens and no file exceeds 12k; test/source token ratio at least 0.3; at least 70% of the code is typed. 50% of modules fit 32k tokens; 1 files over 12k
• ✓ L4 No import cycles, and agent docs (AGENTS.md, CLAUDE.md, llms.txt). AGENTS.md